@smartico/public-api 0.0.380 → 0.0.382

package/docs/Callbacks.md

@@ -0,0 +1,162 @@
+# Event callbacks — `_smartico.on(...)`
+
+Beyond the request/response `_smartico.api.*` methods, the SDK emits **lifecycle
+and engagement events** you can subscribe to. Register a handler with
+`_smartico.on(...)` and it fires whenever that event occurs — user identified,
+balance changed, gamification widget opened, mini-game won, jackpot hit, etc.
+
+This is the push side of the SDK: instead of polling, you react to events as
+they happen.
+
+## Registering and removing handlers
+
+```js
+// Subscribe (works after smartico.js has loaded)
+_smartico.on('identify', (errCode, props) => {
+  console.log('[smartico] user identified — render the logged-in UI');
+});
+
+// The queue form also works BEFORE the library finishes loading — the call
+// is queued and replayed once smartico.js is ready. Use this when wiring
+// handlers in your page <head> before the script loads.
+_smartico('on', 'identify', (errCode, props) => { /* ... */ });
+
+// Remove a specific handler
+function onProps(props) { /* ... */ }
+_smartico.on('props_change', onProps);
+_smartico.off('props_change', onProps);
+
+// Passing null removes ALL handlers registered for that key
+_smartico.on('props_change', null);
+```
+
+### Behavior
+
+- **Multiple handlers per event stack.** Calling `on` repeatedly for the same
+  key adds handlers; they all fire. Use `off(key, fn)` to remove one, or
+  `on(key, null)` to clear all for that key.
+- **Handlers fire asynchronously** (on the next tick) and are isolated — a
+  handler that throws logs a warning and does NOT prevent the other handlers
+  (or the SDK) from running. Don't rely on execution order between handlers.
+- **Works in both authenticated and visitor mode.** A handler registered via
+  `_smartico.on(...)` is active whether the session is a logged-in user or a
+  visitor (`_smartico.vapi(...)`). Events that require an account (`identify`,
+  `login`, `logout`) simply never fire in visitor mode — see the per-event
+  notes below.
+- **Late subscription misses past events.** `on` does not replay events that
+  already happened. If you subscribe to `init` after the library has already
+  initialized, your handler won't be called. For one-time lifecycle events
+  (`init`, `identify`), register early (use the `_smartico('on', ...)` queue
+  form in your page head).
+
+## Event reference
+
+The first argument of `_smartico.on(...)` is the event key — one of the
+strings below.
+
+### Lifecycle
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `init` | The SDK has finished loading and initializing. Fires shortly after `_smartico.init(...)`, **before** the user is identified. | `(errCode)` — `0` on success |
+| `label_init_completed` | The label configuration / settings have loaded (the handshake that follows `init`). At this point gamification products are known. | `(errCode, message)` |
+| `identify` | A user identify attempt completes — **both success and failure**. Branch on `errCode`. | `(errCode, props, message)` on success; `(errCode, {})` on failure. Not fired in visitor mode. |
+| `login` | A login completes successfully. | `()` — no arguments. Not fired in visitor mode. |
+| `logout` | A logout completes successfully. | `()` — no arguments. Not fired in visitor mode. |
+
+### User state
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `props_change` | Any public user property changes — points, level, balances (gems/diamonds), avatar, unread inbox count, nickname, etc. Fires once right after identify with the full initial set, then again on each change with the changed subset. | `(props)` — a partial public-properties object containing the changed fields. `avatar_id` is returned as a fully-qualified URL. |
+| `page_navigation` | A page load or SPA route change is detected. | `({ url, prev_url, referrer, source })` — `source` is `'load'` (initial page load) or the navigation trigger. |
+| `session_based_dp_detected` | A deep link stored earlier in the browser session is detected after identify (and is about to be executed). | `()` — no arguments. |
+
+### Gamification widget lifecycle
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `gf_starting` | The main gamification widget begins opening (e.g. the user taps the gamification entry point or a deep link opens it). | `()` |
+| `gf_started` | The gamification widget has rendered and is displayed to the user. Fires after `gf_starting`. | `()` |
+| `gf_closing` | The gamification widget (or a standalone mini-game) begins closing. | `()` |
+| `saw_starting` | A standalone mini-game surface (Spin-a-Wheel / MatchX / Quiz) begins opening. | `()` |
+| `inbox_starting` | The standalone inbox widget begins opening. | `()` |
+| `gf_ux` | A screen-view / UX analytics event occurs inside the gamification widget (the user navigates to a screen or section). Use to mirror in-widget navigation into your own analytics. | `({ screen_name_id, custom_section_id, entity_id, screen_subname_id })` |
+
+### Wins and game launches
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `mini_game_win` | A mini-game spin finishes and a prize is determined. Fires for both real and visitor-mode plays. | `({ prize_id, name, visitor_win_uuid })` — `name` is the prize display name. In visitor mode, `visitor_win_uuid` can be passed to `_smartico.convertVisitorGame(uuid)` to attach the win to a real account on registration. |
+| `jackpot_win` | A jackpot the user participates in is hit (the pot explodes and the user is among the recipients). | `(message)` — the win payload (winner details + jackpot info). See the Jackpots UI guide (`docs/ui/jackpots/`) for how the default Smartico UI surfaces wins. |
+| `ach_game_opening` | The user taps a related / eligible casino game tile from inside the gamification widget (mission, tournament, jackpot, or store context). Use this to launch the game in your own casino lobby. | `(game)` — the game object (catalog id, name, launch links, plus a `context` field naming where it was opened from). If you do not handle this event, the default Smartico UI opens the game's configured link itself. |
+
+### Errors
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `protocol_error` | The server rejected a request as an unsupported command (a protocol-level error, distinct from a method's `err_code`). | `({ errCode, errMsg })` |
+
+## Examples
+
+### Keep a balance widget live
+
+```js
+// Render once on identify, then patch on every change.
+_smartico.on('identify', (errCode, props) => {
+  if (errCode === 0) {
+    console.log('[smartico] initial balance — render widget:', props.ach_points_balance);
+  } else {
+    console.error('[smartico] identify failed — show logged-out state');
+  }
+});
+
+_smartico.on('props_change', (props) => {
+  if (props.ach_points_balance !== undefined) {
+    console.log('[smartico] points changed — update the balance widget:', props.ach_points_balance);
+  }
+  if (props.core_inbox_unread_count !== undefined) {
+    console.log('[smartico] unread count changed — update the inbox badge:', props.core_inbox_unread_count);
+  }
+});
+```
+
+### React to a mini-game win
+
+```js
+_smartico.on('mini_game_win', ({ prize_id, name, visitor_win_uuid }) => {
+  console.log('[smartico] user won prize', prize_id, '—', name, '— show your own celebration overlay');
+
+  if (visitor_win_uuid) {
+    console.log('[smartico] visitor win — after the user registers, call _smartico.convertVisitorGame to attach this win');
+  }
+});
+```
+
+### Launch casino games from the gamification widget yourself
+
+```js
+// Take over game launching so games open in your lobby instead of the
+// default link-open behavior.
+_smartico.on('ach_game_opening', (game) => {
+  console.log('[smartico] user wants to play game — launch it in your lobby:', game.ext_game_id, '(context:', game.context + ')');
+});
+```
+
+### Mirror in-widget navigation into your analytics
+
+```js
+_smartico.on('gf_ux', ({ screen_name_id, custom_section_id, entity_id }) => {
+  console.log('[smartico] gamification screen view — forward to your analytics:', screen_name_id, custom_section_id, entity_id);
+});
+```
+
+## Notes
+
+- The handler argument shapes above describe what the SDK passes today. Treat
+  unfamiliar fields defensively (optional-chain / null-check) — payloads can
+  gain fields over time.
+- For request/response data (the current list of missions, the user profile,
+  the jackpot pots, etc.), use the `_smartico.api.*` methods (see the API
+  reference). Callbacks are for reacting to events; the API methods are for
+  fetching and mutating state.

package/docs/SmarticoObject.md

@@ -0,0 +1,445 @@
+# The `_smartico` object — core methods
+
+The global `_smartico` object is the entry point to the SDK. It has three
+surfaces:
+
+- **Core methods** (this document) — `init`, identify, language, deep links,
+  embedding widgets, push, etc. These are top-level calls: `_smartico.<method>(...)`.
+- **`_smartico.api.*`** — the gamification data/mutation API (missions, store,
+  jackpots, …). See the API reference.
+- **`_smartico.on(...)`** — lifecycle/engagement event callbacks. See the Event
+  callbacks reference (`docs/Callbacks.md`).
+
+## Two ways to call
+
+```js
+// Direct form — after smartico.js has loaded.
+_smartico.init('LABEL_API_KEY');
+
+// Queue form — safe to call BEFORE the library finishes loading. Calls are
+// queued and replayed once the script is ready. Use this in your page <head>.
+_smartico('init', 'LABEL_API_KEY');
+_smartico('on', 'identify', () => { /* ... */ });
+```
+
+The standard integration snippet (see
+https://help.smartico.ai/welcome/technical-guides/front-end-integration)
+defines `_smartico` as a queue function, then loads the library which drains
+the queue. Both forms map to the same methods.
+
+---
+
+## Setup & identity
+
+### `init(label_api_key, params?)`
+
+Initializes the library for a label. Must be called once before anything else.
+
+- **Idempotent** — calling `init` again with the same label key is a no-op.
+  Calling it with a **different** label key (or after visitor mode) tears down
+  and re-initializes.
+- Fires the `init` callback (~immediately after setup; see the Event callbacks
+  reference).
+- `params` is optional configuration. Common fields: `brand_key` (string),
+  `lang` (default `'EN'`), `visitor_mode` (boolean), `debug` (boolean).
+
+```js
+_smartico('init', 'YOUR_LABEL_API_KEY', { brand_key: 'main', lang: 'EN' });
+```
+
+### `initVisitorMode(label_api_key, params?)`
+
+Shorthand for `init(label_api_key, { ...params, visitor_mode: true })` —
+enables visitor (unauthenticated) features. See the "Visitor mode" section
+in the project README and use `_smartico.vapi(lang)` for visitor data calls.
+
+### `online(ext_user_id, language, user_hash, payload?)`
+
+Identifies (logs in) a user. This is the recommended single call to attach a
+real user to the session — it identifies the user, clears any cached data from
+a previous session, and applies the language in one step.
+
+- `ext_user_id` — the operator's user id. Required (throws if empty).
+- `language` — 2-letter language code; applied via `changeLanguage`.
+- `user_hash` — the server-issued authentication hash for the user.
+- Fires the `identify` callback (success or failure) and, on success, the
+  `login` callback. After it resolves, `_smartico.api.*` calls act on behalf
+  of this user.
+
+```js
+_smartico('online', 'user-123', 'EN', 'SERVER_ISSUED_HASH');
+```
+
+**Login-event window**: the `login` event is generated when a new session
+starts. Within ~30 minutes, page refreshes / navigations do NOT re-trigger
+`login`. If the user logs out on your site you MUST call `_smartico.logout()`
+explicitly — otherwise a subsequent login within the 30-minute window won't
+re-trigger `login`.
+
+### Identifying via global variables (alternative)
+
+Instead of calling `online` / `identify`, you can set the user identity through
+globals before the library initializes — the SDK reads them on init:
+
+```html
+<script>
+  window._smartico_user_id = 'some_id';
+  window._smartico_language = 'fr';
+  // Optional but recommended when ext ids are guessable — see hash note below.
+  window._smartico_user_hash = '019b370929095f0cfe6c9b02ea7524a2:1638050700000';
+</script>
+```
+
+**Hash protection**: when `ext_user_id` is guessable (sequential number,
+username, …), pass a `user_hash` so a third party can't impersonate a user.
+The hash is `md5( (ext_user_id + ':' + salt_key + ':' + validity_ts_ms).toLowerCase() ) + ':' + validity_ts_ms`,
+**computed server-side**. The salt key is issued by your Smartico Success
+Manager and must be kept secret.
+
+### `identify(ext_user_id, hash, payload?)` · `login(language?, payload?)`
+
+The older identify/login pair. `identify` attaches the user; `login` sets the
+login payload and (optionally) the language. Both are being consolidated into
+`online(...)` — prefer `online` for new integrations. `identify` throws if
+`ext_user_id` is empty.
+
+### `logout(payload?)`
+
+Logs the current user out, forgets the session, and reconnects as anonymous.
+Fires the `logout` callback on success.
+
+### `changeLanguage(language)`
+
+Switches the active language. The code is normalized to a 2-letter form
+(`en-US` → `en`). Changing the language clears the SDK data caches so
+subsequent `_smartico.api.*` calls return content in the new language. Throws
+if `language` is missing.
+
+### `clear(params?)`
+
+Tears down the tracker, clears caches and timers, and forgets the session.
+Used when fully resetting the SDK (rarely needed directly — `init` with a new
+label key calls this for you).
+
+---
+
+## User profile
+
+### `getPublicProps()`
+
+Returns a synchronous snapshot of the user's current public properties, or
+`null` if the SDK isn't initialized yet. For live updates, subscribe to the
+`props_change` event (see the Event callbacks reference). For the rich typed
+profile, use `_smartico.api.getUserProfile()`.
+
+Commonly-used properties:
+
+| Property | Meaning |
+|---|---|
+| `avatar_id` | Avatar image URL |
+| `ach_points_balance` / `ach_gems_balance` / `ach_diamonds_balance` | Current currency balances |
+| `ach_points_ever` | Lifetime points earned |
+| `ach_level_current` | Current level name |
+| `core_inbox_unread_count` | Unread inbox messages |
+| `core_public_tags` | Array of upper-cased user tags (see `updatePublicTags`) |
+| `ach_gamification_in_control_group` | `true` when gamification is DISABLED for this user (control group) |
+| `core_registration_date` | Set once the server-side profile is ready |
+
+**Control group**: use `ach_gamification_in_control_group` to hide your
+gamification entry points for users gamification is disabled for. Keep the
+entry hidden by default and reveal it only when the flag is `false`:
+
+```js
+_smartico.on('props_change', (props) => {
+  if (props.ach_gamification_in_control_group !== undefined) {
+    const btn = document.getElementById('rewards-btn');
+    btn.style.display = props.ach_gamification_in_control_group ? 'none' : 'block';
+  }
+});
+```
+
+### `setNickname(nickname)`
+
+Sets the user's public display name.
+
+### `setAvatar(avatar_id)`
+
+Sets the user's avatar — pass the URL of a PNG with a 1:1 (square) proportion.
+For the full avatar catalog / AI-customization flow, use the `_smartico.api`
+avatar methods instead.
+
+```js
+_smartico.setAvatar('https://somesite.com/avatar.png');
+```
+
+### `setSkin(skin_name)`
+
+Switches the gamification widget's visual skin (e.g. `'v3_base_dark'`,
+`'v3_base_vip'`). Useful for matching a day/night site theme, or for giving
+specific users a special skin:
+
+```js
+_smartico.on('props_change', (props) => {
+  if (props.ach_level_current === 5) {
+    _smartico.setSkin('v3_base_vip');
+  }
+});
+```
+
+### `updatePublicTags(operation, tags?)`
+
+Mutates the user's public tags. `operation` is one of `'add'`, `'remove'`,
+`'replace'`, `'clear'`. Tags can also be set server-side from campaigns /
+automation rules, and read on the client via `props.core_public_tags` (an
+array of upper-cased tag strings) on the `props_change` event.
+
+```js
+_smartico.updatePublicTags('add', ['A', 'B']);   // add A & B
+_smartico.updatePublicTags('remove', ['A']);     // remove A
+_smartico.updatePublicTags('replace', ['C', 'D']); // replace all with C & D
+_smartico.updatePublicTags('clear');             // clear all
+```
+
+### `setUTMs(core_utm_source, core_utm_campaign)`
+
+Attaches UTM attribution to the user's profile.
+
+---
+
+## Deep links & embedding the gamification UI
+
+### `dp(deepLink)`
+
+Executes a **deep link** — the primary way to open Smartico gamification
+surfaces from your own UI (buttons, menu entries, etc.). Pass a deep-link
+string such as:
+
+| Deep link | Opens |
+|---|---|
+| `dp:gf` | Gamification main widget |
+| `dp:gf_missions` | Missions screen |
+| `dp:gf_badges` | Badges screen |
+| `dp:gf_store` | Store screen |
+| `dp:gf_tournaments` | Tournaments screen |
+| `dp:gf_board` | Leaderboard |
+| `dp:gf_bonuses` | Bonuses screen |
+| `dp:inbox` | Inbox |
+
+```js
+// Open the gamification hub when the user taps your "Rewards" button.
+document.querySelector('#rewards-btn').addEventListener('click', () => {
+  _smartico.dp('dp:gf');
+});
+```
+
+Works for identified users, and for visitors when visitor mode is enabled.
+If called before the user is ready, it logs a console error and no-ops.
+
+Special deep links beyond the gamification screens include
+`dp:ask_push_permissions` (trigger the browser push-permission dialog) and
+`dp:action&action=YOUR_ACTION` (fire a named client action).
+
+**Triggering a deep link from a URL**: pass a URL-encoded deep link in the
+page URL hash as `_smartico_dp=...` and the SDK executes it automatically
+after the user is identified — handy for triggering a campaign when a user
+lands on a specific page:
+
+```text
+https://mycasino.com/deposit.html#_smartico_dp=dp%3Aaction%26action%3DDEPOSIT_OPENED
+```
+
+### `miniGame(saw_template_id, params?, pending_message_id?)`
+
+Opens a specific mini-game (Spin-a-Wheel / lootbox / etc.) by its template id.
+Requires an identified user — for mini-games on landing pages to visitors, use
+`showVisitorGame` instead.
+
+### `showWidget(widgetType, params?)`
+
+Embeds a pre-built Smartico widget. `widgetType` is one of:
+
+`'achievements'`, `'short_info'`, `'tournaments'`, `'store'`, `'inbox'`,
+`'missions'`, `'mini-game'`, `'match-x-2'`, `'quiz'`, `'custom-section'`,
+`'inbox-widget'`, `'ui-widget'`, `'liquid'`.
+
+`params` controls embedding (e.g. `iframe` target element id, `height`,
+`theme`, `inline`, `force_mobile`). Requires an identified user.
+
+### `gamificationBlock({ dom_id, url })`
+
+Mounts a Smartico landing-page widget bundle (built in the LP IDE) into a host
+element on your page. `dom_id` is the id of the container; `url` is the
+absolute URL of the published `widget.js`. Re-calling with the same `dom_id`
+cleanly remounts (the previous widget is torn down first). Requires `init`
+to have run.
+
+### `showBanner({ dom_id, placement_key })` · `sendDataToBanner({ placement_key, data })`
+
+Renders an operator-configured banner into a host element, and pushes runtime
+data into a rendered banner placement.
+
+### `suspendPopups(flag)` · `suspendInbox(flag)` · `suspendMiniGames(flag)`
+
+Temporarily suppress (or re-enable) automatically-triggered surfaces — popups,
+inbox prompts, and server-triggered mini-game pop-ups respectively. Pass `true`
+to suspend, `false` to resume. Useful while the user is mid-flow (e.g. on a
+deposit page or completing a KYC form) and you don't want Smartico surfaces
+interrupting. Require an identified user.
+
+```js
+_smartico.suspendPopups(true);   // on a checkout page
+// ...later...
+_smartico.suspendPopups(false);  // back to a safe screen
+```
+
+When suspension is turned off, the first surface that was missed while
+suspended is shown — provided the session is still active (the user hasn't
+refreshed or navigated away).
+
+---
+
+## Events & analytics
+
+### `event(eventType, payload?)`
+
+Sends a client event to Smartico (drives automation rules, missions, etc.).
+
+### `action(actionValue, extraPayload?)`
+
+Sends a named client action — a lightweight event keyed by an action string,
+with optional custom payload you can evaluate later in journeys / automation
+rules / missions.
+
+```js
+_smartico.action('CashierSubmitClicked');
+_smartico.action('PIGGY-BANK-CLICK', { prize: 'ABC' });
+```
+
+### `setLoginEntry(core_last_login_entry)`
+
+Records the entry point / context of the user's current login (e.g.
+`'LOBBY'`, `'MOBILE_APP'`) so you can segment / react by it. Any string is
+accepted, but a label is limited to 50 distinct entry-point values.
+
+```js
+_smartico.setLoginEntry('LOBBY');
+```
+
+### `sendAnalytics(activity_id, view_time_sec?)`
+
+Reports a screen/activity impression for analytics.
+
+### `on(key, handler, params?)` · `off(key, handler)`
+
+Subscribe / unsubscribe to lifecycle and engagement events (`identify`,
+`props_change`, `mini_game_win`, `jackpot_win`, …). Registered handlers fire in
+both authenticated and visitor mode. See the **Event callbacks reference**
+(`docs/Callbacks.md`) for the full event list and handler arguments.
+
+---
+
+## Push notifications
+
+### `requestPushPermissions()`
+
+Prompts the user for web-push permission and registers the subscription. Works
+for an identified user OR an anonymous visitor — the push token is registered
+automatically on the Smartico side once the user is identified. Can also be
+triggered as a deep link: `_smartico.dp('dp:ask_push_permissions')`.
+
+### `registerNativePushToken(token, platform?, app_package_id?)`
+
+Registers a native (mobile app) push token for the identified user.
+
+---
+
+## Visitor games
+
+### `showVisitorGame(params)`
+
+Plays a mini-game for an unidentified visitor (visitor mode must be enabled).
+`params`: `{ template_id, frame_id, onBeforePlay, onWin }` — `onBeforePlay`
+returns a boolean to gate the play; `onWin(prize)` receives the won prize.
+
+### `convertVisitorGame(visitor_win_uuid)`
+
+Attaches a visitor's win to a now-identified account — call after the visitor
+registers / logs in, passing the `visitor_win_uuid` from the visitor win (also
+delivered on the `mini_game_win` event).
+
+---
+
+## Data API access
+
+### `api`
+
+The gamification data/mutation API object — `_smartico.api.getMissions()`,
+`_smartico.api.buyStoreItem(...)`, etc. Available once the user is identified.
+See the API reference for the full method catalogue.
+
+### `vapi(language)`
+
+Returns a visitor-mode data API object for the given language —
+`_smartico.vapi('EN').getLevels()`. Use when running in visitor mode. Returns
+`null` if the SDK isn't initialized.
+
+---
+
+## Utilities
+
+### `isMobile()`
+
+Returns `true` on mobile user agents.
+
+### `parseUrl()` · `parseUrlHash()`
+
+Parse the current page URL / URL hash into an object (helpers for reading
+query / hash parameters).
+
+---
+
+## Setup notes
+
+### IFrame bridge (B2B)
+
+When the integrated platform is loaded inside an iframe and is NOT the owner of
+the main window, the host (main-window) site loads only `smartico.js` without
+initializing, and the iframe loads `smartico_inframe.js` and makes the same
+calls against a **`_smartico_inframe`** object instead of `_smartico`:
+
+```html
+<script>
+  (function(d,r,b,h,s){h=d.getElementsByTagName('head')[0];s=d.createElement('script');s.onload=b;s.src=r;h.appendChild(s);})
+  (document, 'https://libs.smartico.ai/smartico_inframe.js', function() {
+    _smartico_inframe.init('__your_label_key', { brand_key: '__your_brand_key__' });
+    _smartico_inframe.online('some_user_id', 'fr');
+    _smartico_inframe.dp('dp:gf');
+  });
+</script>
+```
+
+Contact your Customer Success Manager to confirm whether your setup needs this.
+
+### Local development
+
+By default the SDK refuses to run on `localhost` (to avoid creating "phantom"
+users from dev/QA environments). To run against a real/production user during
+local development:
+
+```js
+window._smartico_allow_localhost = true;
+```
+
+## Notes
+
+- Most methods require `init` to have completed; calls made too early log a
+  console error and no-op rather than throwing (except `online` / `identify`,
+  which throw on an empty `ext_user_id`, and `changeLanguage`, which throws on
+  a missing language).
+- Client events (`event` / `action`) travel over a public, untrusted channel —
+  use them only for non-sensitive signals (screen views, clicks). Custom events
+  must be registered with your Customer Success Manager before use.
+- The method argument shapes above reflect current behavior; treat optional
+  `params` objects defensively as they can gain fields over time.
+- For runnable, copy-pasteable widget code built on `_smartico.api.*`, see
+  [expo.smartico.ai](https://expo.smartico.ai/widgets/intro).