FAQs - Technical Integration

Architecture & Authentication

1. Q: What are the two API gateways I need to integrate, and why do both exist?

   A: The Platform API Gateway connects your backend to ingest data (bulk + real-time). The Frontend API Gateway authenticates players and powers widgets/real-time UI. You’ll generally use Platform for server→server ingestion/sync and Frontend for player-scoped reads/UI.

2. Q: Which auth flow should my backend use for Platform API calls?

   A: OAuth 2.0 Client Credentials to obtain a JWT access token; use the published token URL and include the token when calling Platform REST/RX/Data Fetch endpoints.

3. Q: How do players authenticate to the Frontend API Gateway?

   A: Your FE calls {PEP_FE}/api/auth/v1/player with your clientId and your identityToken (e.g., your casino session ID). PEP calls your /api/auth/v1/player to validate, then issues a JWT the widgets/FE use (via x-authorization).

4. Q: Do I need to build an Operator endpoint for player validation?

   A: Yes—implement POST {operator}/api/auth/v1/player that validates the identityToken and returns playerId (+ optional expiresAt). PEP relies on this to mint the player JWT.

5. Q: Where do I put the player JWT when calling PEP FE endpoints directly?

   A: In the x-authorization header (widgets handle this for you if you use them).

6. Q: Can I skip Frontend auth if I only use widgets?

   A: No—you still must provide an identity token so PEP can validate the player and issue its JWT; the widgets simplify, but don’t eliminate, the auth requirement.

7. Q: What’s the difference between “ingestion” and “reactive” APIs?

   A: Ingestion is for bulk/periodic sync (e.g., initial loads); reactive is real-time event feeds that instantly drive missions/segments/triggers. You’ll need both for a complete integration.

8. Q: Is there a single token for all Platform APIs?

   A: Yes—obtain a Platform OAuth token and reuse it across Platform REST, RX (reactive), and Data Fetch calls until expiry.

9. Q: Does the Platform auth flow return a JWT?

   A: Yes—the Client Credentials flow yields a JWT access token you include on subsequent Platform calls.

10. Q: Do I need to define OAuth Clients in PEP Admin?

    A: Yes—create Client Credentials in Admin to call Platform/Data Fetch; you also create FE client IDs there.

---

Frontend SDK & Widgets

1. Q: How do I load the v2 widgets bundle?

   A: Include the v2 script from your region CDN, then call GamanzaEngageClient.init(config, cb). Use getInstance(cb) later to safely access GamificationWidgets.

2. Q: What happens if I call getInstance before init finishes?

   A: The callback receives null; implement a fallback to (re)call init or postpone usage.

3. Q: How do I render widgets in SPA routes that mount DOM nodes later?

   A: Use GamificationWidgets.reload() (or reloadOne(id)) after new nodes appear so the library scans and attaches widgets.

4. Q: What DOM structure do widgets expect?

   A: Elements with class gamification_widget and a data-type like avatar, reward-shop, active-boosters, etc.

5. Q: How can I get the current player basics (e.g., opt-in) from the SDK?

   A: Use GamificationWidgets.getPlayer(cb) (exposed via getInstance) and listen for the GamanzaEngage_Client_Initialized event to know initial fetch finished.

6. Q: What’s the clean-up hook on logout?

   A: Call GamificationWidgets.destroyWidgets() to clear Redux/local storage/socket and tear down the instance.

7. Q: Is v1 of the client still supported?

   A: v1 is deprecated; use v2 bundle and APIs.

8. Q: Do the widgets provide real-time updates?

   A: Yes—the FE gateway + widgets leverage SocketIO for player progress/notifications updates once authenticated.

9. Q: Can I localize widget labels dynamically?

   A: Yes—re-render with reload(newLocale) or reloadOne(id, newLocale) after updating locale in your app state.

10. Q: What’s the minimal markup to show active boosters?

    A: <div class="gamification_widget" data-type="active-boosters"></div> (after init).

Rewards, XP, Tokens & Bundles

1. Q: What’s the API to credit XP to many players at once?

   A: POST /v1/platform-api/xp-bulk/credit (bulk XP). Plan for 202/4xx/5xx handling.

2. Q: Can I credit virtual currency coins too?

   A: Yes—use the Credit Virtual Currency Coins APIs under “Credit Experience Points and Tokens”.

3. Q: Can I assign multiple reward types in a single request?

   A: Yes—configure a rewards bundle (e.g., XP booster + tokens + XP) in one assignation.

4. Q: Any rate limits on reward crediting?

   A: Yes—100 req/min for crediting APIs (sliding window throttling).

5. Q: Best practices when assigning rewards?

   A: Provide meaningful reason/source strings for auditing; implement robust error handling; max 1000 assignations per request.

6. Q: Does assigning rewards reflect in Admin UI and Widgets?

   A: Yes—assignations surface in “My Rewards”/Admin and FE widgets when configured.

---

CRM Channels & Mobile Push

1. Q: How do I enable native iOS/Android push via CRM?

   A: Configure OneSignal (App ID/API Key) in Admin; ensure OneSignal’s External ID = Player ID and register the subscription with CRM.

2. Q: We wrap the website into a native shell with Median—any shortcut?

   A: Yes—if using Median.co with Widgets configured, PEP can auto-register OneSignal subscriptions.

3. Q: Where do on-site/web notifications come from?

   A: From the Frontend gateway + widgets stack (SocketIO + CRM channel features) once the player is authenticated.

4. Q: Can “risked” players still receive push?

   A: Risk blocks CRM marketing sends (respect jurisdictional rules). Operational/mandatory messages are your compliance call; PEP’s Risk module is designed to suppress marketing specifically.

---

Webhooks & Operator APIs

1. Q: Can PEP push events to my systems instead of me polling?

   A: Yes—configure Event Webhooks (name, callback URL, select event types) in Admin; PEP will POST payloads to your endpoint.

2. Q: How do you secure webhooks?

   A: PEP implements webhook security features (e.g., signature/validation patterns)—verify payload authenticity before processing.

3. Q: Do I need to expose any operator APIs besides player validation?

   A: Recommended: Assign Bonus and Get Bonuses so PEP/CRM can auto-populate bonus choices and execute bonus awards without manual IDs; also consider a Reconciliation API for player-data completeness.

4. Q: Why a Reconciliation API if I already send CRUD/events?

   A: It’s a fail-safe so PEP can ask your platform to backfill missing fields (regulatory compliance, segmentation integrity), with audit logs.

---

Games metadata, Risk & Misc

1. Q: How do I make my game catalog show nicely in tournaments/widgets?

   A: Publish Games Metadata so PEP can map game IDs to images/launch info and integrate deeply with tournaments/UX.

2. Q: Is there an API to set/reset risk flags?

   A: Yes—Risk REST API includes endpoints to set/remove player risk and list active risks (Platform OAuth). Use it to programmatically block/unblock CRM marketing eligibility.