@smartico/public-api 0.0.346 → 0.0.347

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/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

@@ -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

@@ -3677,7 +3677,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 +3703,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 +5260,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 +5330,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);