@smartico/public-api 0.0.346 → 0.0.348

package/README.md

@@ -40,6 +40,22 @@ _smartico.api.getMiniGames( { onUpdate: miniGamesUpdates} ).then( games => {
 
 See the [API documentation](docs/api/classes/WSAPI.md) for all available methods and returning data.
 
+See [expo.smartico.ai](https://expo.smartico.ai/widgets/intro) for the open-source examples of using the API as React-based components. Available examples:
+
+* [User profile](https://expo.smartico.ai/widgets/user) — display user gamification info (points, level, badges)
+* [Mini-games](https://expo.smartico.ai/widgets/mini_games) — show list of mini-games and trigger a mini-game with a deep link
+* [Prize history](https://expo.smartico.ai/widgets/prize_history) — show user's mini-game prize history
+* [Missions](https://expo.smartico.ai/widgets/missions) — list missions, opt-in, and claim rewards
+* [Store](https://expo.smartico.ai/widgets/store) — display store items and categories, handle purchases
+* [Tournaments](https://expo.smartico.ai/widgets/tournaments) — show tournament lobby and registration
+* [Inbox](https://expo.smartico.ai/widgets/inbox) — inbox messages with read/delete/favorite actions
+* [Custom Level Map](https://expo.smartico.ai/widgets/api_custom_lvl_map) — build a custom level progression map
+* [Custom mini-game via API](https://expo.smartico.ai/widgets/dp_custom_mini_game) — implement a fully custom mini-game using the API
+* [Custom mini-game example](https://expo.smartico.ai/widgets/dp_custom_mini_game_example) — working example of a custom mini-game
+* [Jackpots](https://expo.smartico.ai/jackpots/jp_intro) — jackpot opt-in, custom win animation, multi-jackpot
+* [Raffles](https://expo.smartico.ai/raffles/raffle_intro) — raffle draws, prizes, and draw history
+* [UI Widgets](https://expo.smartico.ai/ui_widgets/dp_ui_widgets) — pre-built UI widgets for mini-games, leaderboard, store, missions, badges, tournaments, levels, and jackpots
+
 ## Visitor mode
 
 You can also get gamification data for the visitors (not authorized users). 
@@ -56,6 +72,43 @@ _smartico.vapi('EN').getLevels().then( levels => {
 
 ```
 
+See [expo.smartico.ai/visitor_api](https://expo.smartico.ai/visitor_api/visitor_api_intro) for open-source examples of the Visitor API:
+
+* [Missions](https://expo.smartico.ai/visitor_api/visitor_api_missions) — display missions available for visitors
+* [Tournaments](https://expo.smartico.ai/visitor_api/visitor_api_tournaments) — show tournament lobby for non-authenticated users
+* [Store](https://expo.smartico.ai/visitor_api/visitor_api_store) — display store items before user login
+* [Custom levels map](https://expo.smartico.ai/visitor_api/visitor_api_custom_lvl_map) — build a custom level map for visitors
+
+## Using in Native apps (iOS/Android)
+
+Smartico supports integration with native iOS and Android applications via a WebSocket-based protocol and a Native Bridge for WebView communication.
+
+### General integration guide
+
+See the full integration guide: [iOS/Android clients integration guide](https://help.smartico.ai/welcome/technical-guides/front-end-integration/ios-android-clients-integration-guide)
+
+### Connection flow
+
+1. Establish a WebSocket connection to the Smartico API endpoint
+2. Send `INIT` (cid: 3) → receive `INIT_RESPONSE` (cid: 4)
+3. Send `IDENTIFY` (cid: 5) → receive `IDENTIFY_RESPONSE` (cid: 6)
+4. Send `LOGIN` (cid: 7) → receive `LOGIN_RESPONSE` (cid: 11)
+5. Session is active — call any API methods (missions, store, mini-games, tournaments, etc.)
+6. Maintain connection with PING/PONG keepalive
+7. Listen for server-initiated events (popups, mini-game triggers, deep links, property changes)
+
+### Gamification widget & popups
+
+The `IDENTIFY_RESPONSE` returns `native_app_gf_url` and `native_app_popup_url` — use these to load gamification and engagement content in a WebView. The native app communicates with loaded web pages through the Native Bridge interface (`SmarticoBridge`).
+
+### Push notifications
+
+Register push tokens via WebSocket (cid: 1003) or via HTTP POST/GET to the Smartico public endpoint. See the [integration guide](https://help.smartico.ai/welcome/technical-guides/front-end-integration/ios-android-clients-integration-guide) for details on reporting delivery, impression, and click events.
+
+### Protocol reference
+
+For the full low-level protocol specification including all API methods (levels, missions, store, mini-games, tournaments, leaderboard, inbox, jackpots, raffles, etc.) and server-initiated events, see [Native Protocol](docs/native/PROTOCOL.md).
+
 ## Backend usage (NodeJS context)
 
 Note: access to the server-to-server API is not provided by default and is a topic for a separate agreement with Smartico.
@@ -84,7 +137,67 @@ response.templates.forEach( t => {
 
 ```
 
-## Development and publishing process
+## Backend usage (http-protocol)
+
+You can make HTTP calls to the Smartico public endpoint to interact with user data server-to-server — for example, to check if a specific user belongs to segment(s).
+
+> **Note:** Usage of backend-based integration is subject to rate limits and additional charges. High/intensive usage may degrade performance of your client setup. Please contact your Smartico account manager for pricing details based on your expected request volume.
+
+### What you will need
+
+- **Endpoint** — has the form `https://imgX.smr.vc/s2s-api`, where `X` corresponds to your environment ID (ask your account manager)
+- **Label public API key**
+- **Brand public API key**
+
+### Example: check segment membership
+
+This example checks whether a user belongs to specific segments. It corresponds to `checkSegmentListMatch` (cid: 161 / response cid: 162) described in [Native Protocol](docs/native/PROTOCOL.md).
+
+**Request:**
+
+```bash
+curl --location 'https://imgX.smr.vc/s2s-api' \
+--header 'Content-Type: application/json' \
+--data '{
+  "api_key": "your-label-public-api-key",
+  "brand_key": "your-brand-public-api-key",
+  "ext_user_id": "your-user-ext-id",
+  "cid": 161,
+  "uuid": "f07f0730-4886-4135-81b7-62c94659d3cf",
+  "ts": 1770278728317,
+  "segment_id": [
+    6493, 1234
+  ]
+}'
+```
+
+**Response:**
+
+```json
+{
+    "segments": [
+        {
+            "segment_id": 6493,
+            "is_matching": true
+        },
+        {
+            "segment_id": 1234,
+            "is_matching": false
+        }
+    ],
+    "errCode": 0,
+    "errMsg": "",
+    "cid": 162,
+    "ts": 1770303940950,
+    "uuid": "f07f0730-4886-4135-81b7-62c94659d3cf"
+}
+```
+
+### Using other API methods
+
+You can call any API method described in [Native Protocol](docs/native/PROTOCOL.md) using the same HTTP approach. Build the request body with the appropriate `cid` and method-specific fields, along with `api_key`, `brand_key`, `ext_user_id`, `uuid`, and `ts`. The response will follow the same structure documented for each method.
+
+## For Smartico developers
 
 ### Publishing process
 

package/dist/Base/ClassId.d.ts

@@ -115,6 +115,10 @@ export declare enum ClassId {
     RAF_CLAIM_PRIZE_RESPONSE = 909,
     RAF_OPTIN_REQUEST = 916,
     RAF_OPTIN_RESPONSE = 917,
+    BNR_GET_BANNER_PLACEMENTS_REQUEST = 950,
+    BNR_GET_BANNER_PLACEMENTS_RESPONSE = 951,
+    BNR_GET_BANNER_CONTENT_REQUEST = 952,
+    BNR_GET_BANNER_CONTENT_RESPONSE = 953,
     REGISTER_PUSH_NOTIFICATIONS_TOKEN_REQ = 1003,
     REGISTER_PUSH_NOTIFICATIONS_TOKEN_RESP = 2003,
     CLIENT_DEBUG_REQUEST = 77777,

package/dist/SmarticoAPI.d.ts

@@ -11,7 +11,7 @@ import { GetTournamentInfoResponse, GetTournamentsResponse, TournamentRegisterRe
 import { LeaderBoardDetails, LeaderBoardPeriodType } from './Leaderboard';
 import { GetLevelMapResponse } from './Level';
 import { WSAPI } from './WSAPI/WSAPI';
-import { TInboxMessage, TInboxMessageBody, TLevel, TMiniGameTemplate, TMissionOrBadge, TStoreCategory, TAchCategory, TStoreItem, TTournament, TTournamentDetailed, LeaderBoardDetailsT, UserLevelExtraCountersT, TSegmentCheckResult, TUICustomSection, TBonus, TRaffle, TLevelCurrent, TActivityLog } from './WSAPI/WSAPITypes';
+import { TInboxMessage, TInboxMessageBody, TLevel, TMiniGameTemplate, TMissionOrBadge, TStoreCategory, TAchCategory, TStoreItem, TTournament, TTournamentDetailed, LeaderBoardDetailsT, UserLevelExtraCountersT, TSegmentCheckResult, TUICustomSection, TBonus, TRaffle, TLevelCurrent, TActivityLog, TRaffleDraw } from './WSAPI/WSAPITypes';
 import { GetAchievementsUserInfoResponse } from './Core/GetAchievementsUserInfoResponse';
 import { GetJackpotsPotsResponse, GetJackpotsResponse, JackpotsOptinResponse, JackpotsOptoutResponse } from './Jackpots';
 import { GetCustomSectionsResponse } from './CustomSections';
@@ -160,7 +160,10 @@ declare class SmarticoAPI {
     getRaffleDrawRun(user_ext_id: string, payload: {
         raffle_id: number;
         run_id: number;
+        winners_limit?: number;
+        winners_offset?: number;
     }): Promise<GetDrawRunResponse>;
+    getRaffleDrawRunT(user_ext_id: string, raffle_id: number, run_id: number, winners_from?: number, winners_to?: number): Promise<TRaffleDraw>;
     getRaffleDrawRunsHistory(user_ext_id: string, props: {
         raffle_id: number;
         draw_id?: number;

package/dist/WSAPI/WSAPI.d.ts

@@ -77,7 +77,7 @@ export declare class WSAPI {
      * **Visitor mode: not supported**
      */
     getCurrentLevel(): Promise<TLevelCurrent>;
-    /** Returns all the missions available the current user.
+    /** Returns all the missions configured for the current user (server-side scoped, not filtered by Widget visibility).
      * The returned missions are cached for 30 seconds. But you can pass the onUpdate callback as a parameter.
      * Note that each time you call getMissions with a new onUpdate callback, the old one will be overwritten by the new one.
      * The onUpdate callback will be called on mission OptIn and the updated missions will be passed to it.
@@ -257,7 +257,7 @@ export declare class WSAPI {
      * */
     getCustomSections(): Promise<TUICustomSection[]>;
     /**
-     * Returns the list of mini-games available for user
+     * Returns the list of mini-games configured for the current user (not filtered by spin availability or Widget visibility).
      * The returned list of mini-games is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call getMiniGames with a new onUpdate callback, the old one will be overwritten by the new one.
      * The onUpdate callback will be called on available spin count change, if mini-game has increasing jackpot per spin or wined prize is spin/jackpot and if max count of the available user spin equal one, also if the spins were issued to the user manually in the BO. Updated templates will be passed to onUpdate callback.
      *
@@ -735,7 +735,8 @@ export declare class WSAPI {
         onUpdate?: (data: TRaffle[]) => void;
     }): Promise<TRaffle[]>;
     /**
-     * Returns draw run for provided raffle_id and run_id
+     * Returns draw run for provided raffle_id and run_id.
+     * You can pass winners_from and winners_to parameters to get a specific range of winners. Default is 0-20.
      *
      *
      * **Example**:
@@ -759,6 +760,8 @@ export declare class WSAPI {
     getRaffleDrawRun(props: {
         raffle_id: number;
         run_id: number;
+        winners_from?: number;
+        winners_to?: number;
     }): Promise<TRaffleDraw>;
     /**
      * Returns history of draw runs for the provided raffle_id and draw_id, if the draw_id is not provided will return history of all the draws for the provided raffle_id

package/dist/index.js

@@ -144,6 +144,10 @@ exports.ClassId = void 0;
   RAF_GET_TICKETS_RESPONSE = 903,
    RAF_CLAIM_PRIZE_REQUEST = 906,
   */
+  ClassId[ClassId["BNR_GET_BANNER_PLACEMENTS_REQUEST"] = 950] = "BNR_GET_BANNER_PLACEMENTS_REQUEST";
+  ClassId[ClassId["BNR_GET_BANNER_PLACEMENTS_RESPONSE"] = 951] = "BNR_GET_BANNER_PLACEMENTS_RESPONSE";
+  ClassId[ClassId["BNR_GET_BANNER_CONTENT_REQUEST"] = 952] = "BNR_GET_BANNER_CONTENT_REQUEST";
+  ClassId[ClassId["BNR_GET_BANNER_CONTENT_RESPONSE"] = 953] = "BNR_GET_BANNER_CONTENT_RESPONSE";
   /*
       !Important, if adding new messages that are 'acting' on behalf of the client,
       you need to include them in the CLASS_ID_IGNORE_FOR_SIMULATION
@@ -2368,7 +2372,7 @@ var WSAPI = /*#__PURE__*/function () {
       return Promise.reject(e);
     }
   }
-  /** Returns all the missions available the current user.
+  /** Returns all the missions configured for the current user (server-side scoped, not filtered by Widget visibility).
    * The returned missions are cached for 30 seconds. But you can pass the onUpdate callback as a parameter.
    * Note that each time you call getMissions with a new onUpdate callback, the old one will be overwritten by the new one.
    * The onUpdate callback will be called on mission OptIn and the updated missions will be passed to it.
@@ -2679,7 +2683,7 @@ var WSAPI = /*#__PURE__*/function () {
     }
   }
   /**
-   * Returns the list of mini-games available for user
+   * Returns the list of mini-games configured for the current user (not filtered by spin availability or Widget visibility).
    * The returned list of mini-games is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call getMiniGames with a new onUpdate callback, the old one will be overwritten by the new one.
    * The onUpdate callback will be called on available spin count change, if mini-game has increasing jackpot per spin or wined prize is spin/jackpot and if max count of the available user spin equal one, also if the spins were issued to the user manually in the BO. Updated templates will be passed to onUpdate callback.
    *
@@ -3677,7 +3681,8 @@ var WSAPI = /*#__PURE__*/function () {
     }
   }
   /**
-   * Returns draw run for provided raffle_id and run_id
+   * Returns draw run for provided raffle_id and run_id.
+   * You can pass winners_from and winners_to parameters to get a specific range of winners. Default is 0-20.
    *
    *
    * **Example**:
@@ -3702,12 +3707,10 @@ var WSAPI = /*#__PURE__*/function () {
   _proto.getRaffleDrawRun = function getRaffleDrawRun(props) {
     try {
       var _this57 = this;
-      return Promise.resolve(_this57.api.getRaffleDrawRun(null, props)).then(function (res) {
-        if (!props.raffle_id || !props.run_id) {
-          throw new Error('both raffle_id and run_id are required');
-        }
-        return drawRunTransform(res);
-      });
+      if (!props.raffle_id || !props.run_id) {
+        throw new Error('both raffle_id and run_id are required');
+      }
+      return Promise.resolve(_this57.api.getRaffleDrawRunT(null, props.raffle_id, props.run_id, props.winners_from, props.winners_to));
     } catch (e) {
       return Promise.reject(e);
     }
@@ -5261,43 +5264,64 @@ var SmarticoAPI = /*#__PURE__*/function () {
       return Promise.reject(e);
     }
   };
-  _proto.getRaffleDrawRunsHistory = function getRaffleDrawRunsHistory(user_ext_id, props) {
+  _proto.getRaffleDrawRunT = function getRaffleDrawRunT(user_ext_id, raffle_id, run_id, winners_from, winners_to) {
+    if (winners_from === void 0) {
+      winners_from = 0;
+    }
+    if (winners_to === void 0) {
+      winners_to = 20;
+    }
     try {
       var _this72 = this;
-      var message = _this72.buildMessage(user_ext_id, exports.ClassId.RAF_GET_DRAW_HISTORY_REQUEST, props);
-      return Promise.resolve(_this72.send(message, exports.ClassId.RAF_GET_DRAW_HISTORY_RESPONSE));
+      var winners_limit = winners_to - winners_from > 50 ? 50 : winners_to - winners_from;
+      var winners_offset = winners_from;
+      return Promise.resolve(_this72.getRaffleDrawRun(user_ext_id, {
+        raffle_id: raffle_id,
+        run_id: run_id,
+        winners_limit: winners_limit,
+        winners_offset: winners_offset
+      })).then(drawRunTransform);
     } catch (e) {
       return Promise.reject(e);
     }
   };
-  _proto.claimRafflePrize = function claimRafflePrize(user_ext_id, props) {
+  _proto.getRaffleDrawRunsHistory = function getRaffleDrawRunsHistory(user_ext_id, props) {
     try {
       var _this73 = this;
-      var message = _this73.buildMessage(user_ext_id, exports.ClassId.RAF_CLAIM_PRIZE_REQUEST, props);
-      return Promise.resolve(_this73.send(message, exports.ClassId.RAF_CLAIM_PRIZE_RESPONSE));
+      var message = _this73.buildMessage(user_ext_id, exports.ClassId.RAF_GET_DRAW_HISTORY_REQUEST, props);
+      return Promise.resolve(_this73.send(message, exports.ClassId.RAF_GET_DRAW_HISTORY_RESPONSE));
     } catch (e) {
       return Promise.reject(e);
     }
   };
-  _proto.raffleOptin = function raffleOptin(user_ext_id, props) {
+  _proto.claimRafflePrize = function claimRafflePrize(user_ext_id, props) {
     try {
       var _this74 = this;
-      var message = _this74.buildMessage(user_ext_id, exports.ClassId.RAF_OPTIN_REQUEST, props);
-      return Promise.resolve(_this74.send(message, exports.ClassId.RAF_OPTIN_RESPONSE));
+      var message = _this74.buildMessage(user_ext_id, exports.ClassId.RAF_CLAIM_PRIZE_REQUEST, props);
+      return Promise.resolve(_this74.send(message, exports.ClassId.RAF_CLAIM_PRIZE_RESPONSE));
     } catch (e) {
       return Promise.reject(e);
     }
   };
-  _proto.getActivityLog = function getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset) {
+  _proto.raffleOptin = function raffleOptin(user_ext_id, props) {
     try {
       var _this75 = this;
-      var message = _this75.buildMessage(user_ext_id, exports.ClassId.GET_POINT_HISTORY_REQUEST, {
+      var message = _this75.buildMessage(user_ext_id, exports.ClassId.RAF_OPTIN_REQUEST, props);
+      return Promise.resolve(_this75.send(message, exports.ClassId.RAF_OPTIN_RESPONSE));
+    } catch (e) {
+      return Promise.reject(e);
+    }
+  };
+  _proto.getActivityLog = function getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset) {
+    try {
+      var _this76 = this;
+      var message = _this76.buildMessage(user_ext_id, exports.ClassId.GET_POINT_HISTORY_REQUEST, {
         startTimeSeconds: Math.floor(startTimeSeconds),
         endTimeSeconds: Math.floor(endTimeSeconds),
         limit: limit,
         offset: offset
       });
-      return Promise.resolve(_this75.send(message, exports.ClassId.GET_POINT_HISTORY_RESPONSE));
+      return Promise.resolve(_this76.send(message, exports.ClassId.GET_POINT_HISTORY_RESPONSE));
     } catch (e) {
       return Promise.reject(e);
     }
@@ -5310,11 +5334,11 @@ var SmarticoAPI = /*#__PURE__*/function () {
       to = 50;
     }
     try {
-      var _this76 = this;
+      var _this77 = this;
       var limit = to - from > 50 ? 50 : to - from;
       var offset = from;
-      return Promise.resolve(_this76.getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset)).then(function (_this76$getActivityLo) {
-        return ActivityLogTransform(_this76$getActivityLo.logHistory);
+      return Promise.resolve(_this77.getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset)).then(function (_this77$getActivityLo) {
+        return ActivityLogTransform(_this77$getActivityLo.logHistory);
       });
     } catch (e) {
       return Promise.reject(e);