Gami SDK Integration Guide

@momo-cloud/gami-sdk is the integration layer between your web game and MoMo host capabilities. It provides:

• Game backend APIs (spin, shake, mission, leaderboard, balance, exchange)
• Platform bridge APIs (toast, share, permission, contacts, deep-link, calendar, clipboard, and more)
• Runtime utilities (server-time sync, storage helpers, SSE, event bus)

This document is written for engineering teams integrating a game into the MoMo ecosystem.

1) Integration Architecture

At runtime, GamiSDK composes two API groups:

• platformApi.exposeApi: host bridge and device/platform functions
• gamiApi.exposeApi: game-domain APIs and session workflow

Game UI (React/Preact/Pixi)
        |
        v
      GamiSDK
   +-----------+
   | platform  | -> host bridge (toast, share, permission, refId, app events)
   | game api  | -> game services (config, balance, spin, shake, mission, ...)
   +-----------+
        |
        v
MoMo host + backend services

2) Installation

npm install @momo-cloud/gami-sdk

or

yarn add @momo-cloud/gami-sdk

3) Quick Start (Recommended Bootstrap)

import GamiSDK from '@momo-cloud/gami-sdk';
import appJson from '../app.json';

export async function bootstrapGame() {
  await GamiSDK.init({
    gameId: import.meta.env.VITE_DEFAULT_GAME_ID,
    userId: import.meta.env.VITE_USER_ID, // optional in host runtime
    appjson: JSON.stringify(appJson),
    source: 'momo', // optional analytics source
  });
}

4) Integration Phases

Phase A - Initialize SDK

Call once at app startup:

• init({ appjson, gameId?, userId?, source? })
• wait()

Then rely on runtime properties:

• GamiSDK.userId
• GamiSDK.userInfo
• GamiSDK.token
• GamiSDK.gameId
• GamiSDK.appProfile
• GamiSDK.deviceInfo

Phase B - Start Gameplay Session

await GamiSDK.startGame();

Typical game loop calls:

• getConfig()
• getBalance({ balanceId })
• getBalanceConfig()
• spin()
• shake()
• getCoinBalance()
• getCoinExchangeInfo()
• coinExchange({ amount })
• getMission({ viewId? })
• getLeaderboard({ boardId, group?, limit?, page? })
• getHistory({ page, limit })
• getEvent({ eventId })

Phase C - Close or Navigate

• await GamiSDK.endGame() to close session
• GamiSDK.closeApp() to dismiss host view
• GamiSDK.goHome() to return to home

5) Platform Bridge APIs (Most Used)

The SDK exposes host-native actions directly:

• Feedback: showToast, showAlert
• Navigation: openWeb, openURL, startRefId
• Social: shareExternal, shareFacebook, shareMessenger
• Device: scanQRCode, copyToClipBoard, getImage, saveImage
• Permissions: requestPermission, checkPermission
• Contacts and notifications: getContacts, registerNoti, unregisterNoti
• Calendar: saveCalendarEvent
• Analytics: trackingEvent, screenTracking
• Host lifecycle: onFocusApp, onBlurApp, listenShaking

Example:

GamiSDK.showToast({
  description: 'Reward claimed',
  duration: 2000,
  type: 'success',
});

GamiSDK.screenTracking({
  event_name: 'screen_view',
  action_name: 'open_home',
  screen_name: 'home',
});

6) Shared Utilities

Named exports are available for common integration helpers:

• Storage: saveItem, getItem, cacheFile
• Calendar wrapper: addCalendar
• Time sync: setServerTime, getServerTime
• Event bus: GameEvent
• SSE support: from features/sse/*
• Types: from features/types/*

Example:

import { saveItem, getItem, GameEvent } from '@momo-cloud/gami-sdk';

await saveItem('progress', { level: 3, stars: 15 });
const progress = await getItem('progress');

GameEvent.on('GAME_ON_BACK', () => {
  // route back to your home screen
});

7) Error Handling Pattern

Most game APIs return payloads with response_info. Treat non-zero error codes as business failures:

const res = await GamiSDK.spin();
if (res?.response_info?.error_code !== 0) {
  GamiSDK.showToast({
    description: res?.response_info?.error_message || 'Spin failed',
    duration: 2000,
    type: 'failure',
  });
  return;
}

8) Browser vs Host Runtime

• In MoMo host: full platform bridge behavior is available.
• In browser/dev mode: host-only behavior may be mocked, no-op, or limited.

Integration recommendation:

• Keep game domain flow independent from host-only APIs.
• Wrap optional host actions with graceful fallback in browser.

9) Build and Publish Modes

This repository supports two build modes:

• Internal build (src/index.ts): full internal integration surface
• Public build (src/index.public.ts): limited/public package output

Commands:

npm run build:internal
npm run build:public

Publish scripts:

npm run publish:nexus
npm run publish:npm
npm run publish:all

10) Integration Checklist

Before releasing a game integration:

• init() and wait() executed exactly once on app bootstrap
• startGame() called on session start, endGame() on session end
• Critical APIs wrapped with business error handling (response_info)
• Host-only APIs guarded for browser fallback
• Analytics events wired (trackingEvent and screenTracking)
• Local cache keys use SDK helpers to avoid collisions
• Permissions flow validated for calendar/contacts/image capture

11) Minimal End-to-End Example

import GamiSDK from '@momo-cloud/gami-sdk';
import appJson from '../app.json';

export async function run() {
  await GamiSDK.init({
    appjson: JSON.stringify(appJson),
    gameId: import.meta.env.VITE_DEFAULT_GAME_ID,
    userId: import.meta.env.VITE_USER_ID,
  });
  await GamiSDK.wait();

  await GamiSDK.startGame();
  const spinResult = await GamiSDK.spin();

  if (spinResult?.response_info?.error_code === 0) {
    GamiSDK.showToast({ description: 'Spin success', duration: 1500, type: 'success' });
  }

  // Later when leaving the game:
  await GamiSDK.endGame();
}

12) Notes for Architects

• Keep GamiSDK behind your own sdkService adapter in app code.
• Separate domain logic from host bridge calls for easier testability.
• Use typed DTOs from features/types in application boundaries.
• Favor centralized error normalization to avoid duplicated checks.

License: UNLICENSED