Cricap Mini App SDK

Official JavaScript SDK for building mini apps on the Cricap platform. Build, deploy, and monetize your games with seamless integration.

🚀 Quick Start

bash

npm install @cricap/miniapp-sdk

typescript

import { initCricapSDK } from '@cricap/miniapp-sdk';

const sdk = initCricapSDK({
  appId: 'miniapp_your_id',
  environment: 'production',
  debug: true,
});

const result = await sdk.initialize();
if (result.success) {
  await sdk.ui.show({ animation: 'slide-up' });
}

Overview

The Cricap Mini App Ecosystem enables third-party developers to build applications that run within the Cricap platform. This SDK provides seamless integration with authentication, user data, leaderboards, wallet, and real-time notifications.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Cricap Platform                          │
│  ┌──────────────┐    ┌──────────────────────────────────┐  │
│  │   Main App   │    │      Mini App Container          │  │
│  │  (Mobile)    │◄──►│  ┌──────────────────────────┐   │  │
│  │              │    │  │   Mini App (WebView)     │   │  │
│  │  - Auth      │    │  │  ┌────────────────────┐  │   │  │
│  │  - Wallet    │    │  │  │ Your Game/App      │  │   │  │
│  │  - Leaderboard│   │  │  │ + Cricap SDK       │  │   │  │
│  └──────────────┘    │  │  └────────────────────┘  │   │  │
│           │          │  └──────────────────────────┘   │  │
│           ▼          └──────────────────────────────────┘  │
│  ┌──────────────┐                                           │
│  │  Backend API │                                           │
│  │  (REST + WS) │                                           │
│  └──────────────┘                                           │
└─────────────────────────────────────────────────────────────┘

Installation

npm

bash

npm install @cricap/miniapp-sdk

yarn

bash

yarn add @cricap/miniapp-sdk

pnpm

bash

pnpm add @cricap/miniapp-sdk

SDK Initialization

Configuration Options

Option	Type	Required	Description
`appId`	string	✅	Your mini app unique identifier
`environment`	string	✅	`development`, `staging`, or `production`
`version`	string	❌	SDK version (default: latest)
`debug`	boolean	❌	Enable debug logging
`timeout`	number	❌	API timeout in ms (default: 30000)

Basic Initialization

typescript

import { initCricapSDK } from '@cricap/miniapp-sdk';

const sdk = initCricapSDK({
  appId: 'miniapp_12345',
  environment: 'production',
  version: '1.0.0',
  debug: false,
  timeout: 30000,
});

// Initialize with async/await
async function initializeApp() {
  const result = await sdk.initialize();
  
  if (result.success) {
    console.log('SDK initialized:', result.session);
    // Start your mini app
  } else {
    console.error('SDK initialization failed:', result.error);
  }
}

Container Communication

The SDK uses postMessage for bidirectional communication between the mini app (iframe/WebView) and the Cricap container.

Message Protocol

typescript

interface CricapMessage {
  id: string;           // Unique message ID
  type: MessageType;    // Message type
  payload: unknown;     // Message payload
  timestamp: number;    // Timestamp
  source: 'miniapp' | 'container';
}

type MessageType = 
  | 'INIT'
  | 'AUTH_REQUEST' | 'AUTH_RESPONSE'
  | 'USER_INFO_REQUEST' | 'USER_INFO_RESPONSE'
  | 'WALLET_BALANCE_REQUEST' | 'WALLET_BALANCE_RESPONSE'
  | 'LEADERBOARD_REQUEST' | 'LEADERBOARD_RESPONSE'
  | 'NOTIFICATION_SUBSCRIBE' | 'NOTIFICATION_RECEIVE'
  | 'UI_SHOW' | 'UI_CLOSE' | 'UI_RESIZE'
  | 'EVENT_LIFECYCLE' | 'ERROR';

UI Container Methods

Show Mini App

typescript

await sdk.ui.show({
  animation: 'slide-up',  // 'slide-up' | 'fade' | 'none'
  style: 'sheet',         // 'modal' | 'fullscreen' | 'sheet'
  overlay: true,
  closeOnBackdrop: true,
  dimensions: {
    height: '80%',
    maxWidth: 600
  }
});

Close Mini App

typescript

await sdk.ui.close({
  result: { score: 1500, completed: true },
  animation: 'slide-down'
});

Resize Container

typescript

await sdk.ui.resize({
  height: '90%',
  maxHeight: 800
});

Notification System

Subscribe to Topics

typescript

await sdk.notifications.subscribe([
  'leaderboard.updates',
  'wallet.transactions',
  'game.events'
]);

Handle Notifications

typescript

const unsubscribe = sdk.notifications.onNotification((notification) => {
  switch (notification.type) {
    case 'LEADERBOARD_UPDATE':
      updateLeaderboard(notification.data);
      break;
    case 'WALLET_UPDATE':
      refreshWalletBalance();
      break;
    case 'GAME_EVENT':
      handleGameEvent(notification.data);
      break;
  }
});

// Clean up
unsubscribe();

Event Handling

typescript

sdk.events.on('lifecycle:show', () => {
  console.log('Mini app visible');
  resumeGame();
});

sdk.events.on('lifecycle:hide', () => {
  console.log('Mini app hidden');
  pauseGame();
});

sdk.events.on('auth:change', (auth) => {
  if (!auth.authenticated) {
    showLoginPrompt();
  }
});

sdk.events.on('platform:data-update', (data) => {
  if (data.type === 'leaderboard') {
    refreshLeaderboard(data.payload);
  }
});

Backend API - Authentication

Base URLs

Environment	Base URL
Production	`https://api.cricap.com/v1`
Staging	`https://api-staging.cricap.com/v1`

Mini App Registration

POST /miniapps/register

json

// Request
{
  "name": "My Mini App",
  "description": "A description",
  "permissions": ["user:read", "wallet:read", "leaderboard:write"],
  "webhookUrl": "https://myapp.com/webhooks/cricap"
}

// Response (201)
{
  "success": true,
  "data": {
    "appId": "miniapp_abc123",
    "appSecret": "sk_live_xxxxxxxx",
    "apiKey": "pk_live_xxxxxxxx"
  }
}

Token Exchange

POST /auth/token

json

// Request
{
  "grantType": "authorization_code",
  "code": "auth_code_from_container",
  "appId": "miniapp_abc123",
  "appSecret": "sk_live_xxxxxxxx"
}

// Response (200)
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "rt_xxxxxxxx",
    "tokenType": "Bearer",
    "expiresIn": 3600
  }
}

Backend API - User

Get User Profile

GET /users/me

json

// Response (200)
{
  "success": true,
  "data": {
    "userId": "user_xyz789",
    "username": "gamer123",
    "displayName": "Pro Gamer",
    "avatarUrl": "https://cdn.cricap.com/avatars/xyz789.png",
    "stats": {
      "gamesPlayed": 150,
      "totalScore": 125000,
      "rank": "Diamond"
    }
  }
}

Get Wallet Balance

GET /users/me/wallet

json

// Response (200)
{
  "success": true,
  "data": {
    "userId": "user_xyz789",
    "balances": {
      "CRICAP": {
        "symbol": "CRICAP",
        "balance": "1250.50",
        "usdValue": "125.05"
      },
      "USDT": {
        "symbol": "USDT",
        "balance": "500.00",
        "usdValue": "500.00"
      }
    },
    "totalUsdValue": "625.05"
  }
}

Backend API - Platform Data

Get Leaderboard

GET /leaderboard?gameId=my-game&period=daily&limit=100

Submit Score

POST /leaderboard/scores

json

// Request
{
  "gameId": "my-game",
  "score": 150000,
  "metadata": { "level": 25, "timeElapsed": 3600 },
  "proof": { "signature": "sig_xxxxxxxx", "timestamp": 1713675900 }
}

// Response (201)
{
  "success": true,
  "data": {
    "submissionId": "sub_abc123",
    "rank": 5,
    "previousRank": 8,
    "newHighScore": true,
    "rewards": [
      { "type": "token", "symbol": "CRICAP", "amount": "50.00" }
    ]
  }
}

Webhooks

Event Types

Event Type	Description
`user.auth`	User authentication event
`user.wallet.update`	Wallet balance changed
`leaderboard.update`	Leaderboard position changed
`game.event`	Custom game event

Signature Verification

typescript

import { createHmac } from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === `sha256=${expected}`;
}

Error Handling

Code	HTTP	Description
`INVALID_REQUEST`	400	Malformed request
`INVALID_TOKEN`	401	Authentication failed
`INSUFFICIENT_PERMISSIONS`	403	Missing required permissions
`RESOURCE_NOT_FOUND`	404	Requested resource not found
`RATE_LIMITED`	429	Too many requests

Rate Limiting

Endpoint Category	Limit	Window
Authentication	10	60 seconds
User Info	100	60 seconds
Wallet	60	60 seconds
Leaderboard Read	100	60 seconds
Leaderboard Write	30	60 seconds

TypeScript Types

typescript

// SDK Configuration
interface CricapSDKConfig {
  appId: string;
  environment: 'development' | 'staging' | 'production';
  version?: string;
  debug?: boolean;
  timeout?: number;
}

// User Info
interface UserInfo {
  userId: string;
  username: string;
  displayName: string;
  avatarUrl: string;
  stats: {
    gamesPlayed: number;
    totalScore: number;
    rank: string;
  };
}

// Wallet Balance
interface WalletBalance {
  symbol: string;
  balance: string;
  usdValue: string;
}

// Leaderboard Entry
interface LeaderboardEntry {
  rank: number;
  userId: string;
  username: string;
  score: number;
  achievedAt: string;
}

Cricap Mini App SDK v1.0.0

GitHub · npm · Support