Integration guide
Enroll traders, connect activity and rewards, then show each user their Returning.AI widgets. If your backend is already connected, start with the widget quickstart.
Before you start
Ask Returning.AI for the setup values for your environment. You do not need every credential below for every integration. Request only the paths you will use.
- Community: where the users, fields, rules, and widgets are configured.
- Identity mapping: the stable customer identifier and the exact field name used for registration and widget tokens.
- Backend access: the scoped community API key and, when used, the workflow or ingest credentials and agreed payload map.
- Widget setup: the widget ID, full bundle URL, server-side Access ID and Access Key, and allowed portal origin.
- Rules: eligible events, volume units, symbol groups, field definitions, reward rates, and launch/backfill policy.
Your current portal can stay in place. Plain HTML, React, Next.js, Vue, and Angular use the same custom element. Each frontend has a complete optional starter download. HTML, React, Vue and Angular downloads include a Node reference backend; Next.js includes server routes. You can keep another backend by following the shared token contract and its Node.js, PHP or Django examples.
The complete data-to-widget path
There are two connected paths: the backend keeps user state current, and the browser opens a widget for the signed-in user. The widget does not enroll the trader or turn a queue receipt into a reward.
From your systems to the widget
Follow the saved state, not just the first successful request. Not every workflow uses a bulk update job.
- Your backend
Customer registration, account mappings, identity checks, deposits, and eligible trading activity. Keep stable business identifiers and original event times.
- Your sender + Returning.AI
Use the provisioned queue, ingest endpoint, configured webhook, or a specific public API operation. A transport receipt is the start of processing, not a reward receipt.
- Returning.AI
Validate and route the agreed envelope, resolve users, normalize values, and run configured actions. Inspect failures separately from the sender's receipt.
- Returning.AI, when configured
A workflow can hand work to a bulk update job. Check the job and individual row results before assuming every user's update finished; the workflow step can post the job's result to your endpoint when it ends.
- Returning.AI
Read back the authoritative user state. Reconcile volume, field histories, points or coins with the accepted source facts and configured rules.
- Your portal + Widget SDK
The widget reads state for the user in the server-signed token. Data processing and browser refresh are separate steps.
Transport acceptance, ingest validation, workflow execution, queued user updates, saved fields and balances, and widget display are separate checkpoints. If a step is visible only in Returning.AI admin tools, Returning.AI checks it with your batch or event identifier. Do not give your sender admin credentials to fill that gap.
Who owns each part?
| System | Owns | Verify |
|---|---|---|
| Your portal and CRM | Committed customer identity, login, account mappings, lifecycle facts, and secure event delivery. | A trading account resolves to the correct customer; widget tokens use that customer's trusted server session. |
| Your trading source | Deals, source units, symbols, account state, original event time, and replay identity. | Eligible closed activity matches the agreed time window and volume definition. |
| Returning.AI | Configured ingest/workflows, user state, reward rules, milestone conditions, and widget configuration. | Saved values and configured reward outcomes reconcile with source facts. |
| Both teams | Payload contract, failure handling, corrections, environment setup, and launch approval. | A complete synthetic journey passes. |
Build order
Get one trader and one widget working first. Then connect the events that make the experience useful. Referrals are optional; the transport choice depends on what your source can send.
- Enroll traders
Choose a stable customer key, create membership, and verify the account mapping.
- Open your first widget
Use the existing starter once the user is registered. You can connect more data afterward.
- Choose a data path
Pick a buffered trade feed, a configured lifecycle webhook, or a specific API operation.
- Calculate volume and rewards
Follow two trading accounts through asset-class totals and illustrative reward rules.
- Connect onboarding milestones
Save custom fields and check the configured milestone separately.
- Add referrals, if needed
Carry attribution through signup, verify the relationship, and open the referral widget.
- Prove the integration before launch
Check identity, retries, saved values, widget sessions, and who handles failures.
SQS, webhook, or API?
Choose the path for the job. A public API performs a specific operation. A workflow webhook starts configured processing. SQS buffers a feed so receipt and processing can happen at different times.
| Path | Use it for | What a receipt means | Start here |
|---|---|---|---|
| Public community API | Supported user creation, lookup, or a specific field update from your server. | The documented operation's result. Verify saved state and any separate follow-up effects. | Enroll traders |
| Workflow webhook | Signup, identity checks, deposit, or other lifecycle events with a configured workflow. | The configured trigger accepted the request. Inspect workflow output and downstream changes. | Webhook guide |
| SQS / data ingest | Trading facts, agreed aggregates, queued batches, and controlled backfills. | The transport accepted the message or file. It does not confirm every record was processed. | SQS and ingest guide |
| Read-only source pull | A source that cannot push but exposes a suitable API, database, or MetaTrader interface. | The collector retrieved source data. Cursor, mapping, and submission still need verification. | MetaTrader sources |
| Widget Access Key exchange | Opening or refreshing a widget for an already registered, signed-in user. | A short-lived embed token was issued. This is not a data feed or enrollment endpoint. | Widget authentication |
Use the credentials for the path you chose
A community API key, workflow key, ingest key, AWS identity, and widget Access Key are different kinds of access. Keep server credentials out of browser JavaScript. Returning.AI supplies the gateway and permissions for each enabled path.
Follow an example
Onboarding connects a saved field to a configured milestone. Trading maps account activity to asset-class volume and rewards. Referrals carry the referrer's identity through registration before qualification. Each path ends with a saved-state check and an authenticated widget.
Illustrative walkthrough. No integration requests are sent.
- Your source fact
- Your broker system confirms a customer's identity check.
- Configured processing
- Your backend writes the agreed user field, or sends the event to a configured workflow. A configured milestone can use that saved value as a condition.
- What to verify
- Check the saved field first. Then check the milestone condition and its result. An accepted request alone does not prove the milestone completed.
- What the widget shows
- The authenticated onboarding widget reads the user's configured progress.
Know when it works
A green send log is not the finish line. Verify the registered user, the exact source record, the configured processing result, the saved value, and the widget for that same user. Then repeat the agreed duplicate and failure cases without granting rewards twice.
Use the launch checklist and handover sheet to record the environment, owners, evidence, and remaining joint tests.