> For the complete documentation index, see [llms.txt](https://resources.gamanzaengage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://resources.gamanzaengage.com/faq/faqs-technical-integration.md).

# 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

11. 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. 
12. 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. 
13. 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. 
14. Q: What DOM structure do widgets expect?

    A: Elements with class gamification\_widget and a data-type like avatar, reward-shop, active-boosters, etc. 
15. 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. 
16. Q: What’s the clean-up hook on logout?

    A: Call GamificationWidgets.destroyWidgets() to clear Redux/local storage/socket and tear down the instance. 
17. Q: Is v1 of the client still supported?

    A: v1 is deprecated; use v2 bundle and APIs. 
18. Q: Do the widgets provide real-time updates?

    A: Yes—the FE gateway + widgets leverage SocketIO for player progress/notifications updates once authenticated. 
19. 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. 
20. Q: What’s the minimal markup to show active boosters?

    A: \<div class="gamification\_widget" data-type="active-boosters">\</div> (after init).&#x20;

### Rewards, XP, Tokens & Bundles

35. 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.&#x20;
36. Q: Can I credit virtual currency coins too?

    A: Yes—use the Credit Virtual Currency Coins APIs under “Credit Experience Points and Tokens”.&#x20;
37. 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.&#x20;
38. Q: Any rate limits on reward crediting?

    A: Yes—100 req/min for crediting APIs (sliding window throttling).&#x20;
39. Q: Best practices when assigning rewards?

    A: Provide meaningful reason/source strings for auditing; implement robust error handling; max 1000 assignations per request.&#x20;
40. Q: Does assigning rewards reflect in Admin UI and Widgets?

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

***

### CRM Channels & Mobile Push

41. 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.&#x20;
42. 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.&#x20;
43. 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.&#x20;
44. 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.&#x20;

***

### Webhooks & Operator APIs

45. 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.&#x20;
46. Q: How do you secure webhooks?

    A: PEP implements webhook security features (e.g., signature/validation patterns)—verify payload authenticity before processing.&#x20;
47. 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.&#x20;
48. 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.&#x20;

***

### Games metadata, Risk & Misc

49. 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.&#x20;
50. 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.&#x20;


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://resources.gamanzaengage.com/faq/faqs-technical-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.