# Launch checklist

Prove one complete trader journey before launch. Then verify that duplicates, failures, and user changes do not create the wrong rewards or show the wrong account.

## Run one complete acceptance check

Tick each item after checking the result, and record evidence in the handover sheet. These ticks are local page notes, not automated backend tests; they reset when the page is reloaded.

- Create or resolve one synthetic trader and verify usable membership in the intended community.
- Confirm both trading accounts map to that same trader, while another trader remains separate.
- Open the first widget with a server-minted token and the supplied widget ID and bundle URL.
- Follow one eligible source event through transport, workflow, any queued update, and saved state.
- Reconcile volume per asset class, comparable total volume, and the configured reward result.
- Update the agreed onboarding field; verify its saved value and the configured milestone separately.
- If referrals are enabled, verify the referrer relationship separately from signup and reward qualification.
- Exercise the agreed exact duplicate, late event, malformed input, and ambiguous-response cases safely.
- Refresh an expired widget session, sign out, and switch users without showing the previous user's state.
- Record remaining joint UAT, monitoring, pause/replay ownership, and launch approval.

## Close the decisions that block your next step

The sheet below records each unanswered question, accountable role, named contact, required evidence, blocking trigger and status. Ask your setup contact to identify the Returning.AI owner; your team names its own contact. Unassigned ownership does not close a gate.

Confirm membership before minting for that user, session termination before security approval, and privacy terms before sending real customer data. Confirm migration compatibility and rollback before cutover. You can continue unrelated setup with synthetic data while these decisions remain open.

Use an existing applicable agreement for region, retention, export, erasure and support coverage. Do not infer erasure from account removal, infer a service commitment from a successful request, or invent an answer to complete the checklist.

## Copy the integration handover sheet

Both teams should be able to build and operate the integration from this sheet and the linked guides, without searching a chat history. Record labels and owners here; deliver the actual credentials through your approved private channel.

`integration-handover.md`

```markdown
# Integration handover

| Item | Agreed value / owner / evidence |
| --- | --- |
| Environment and community label | TO_FILL |
| Portal origin | https://portal.example.com |
| Stable customer identifier and field name | TO_FILL |
| Trading account to customer mapping | TO_FILL |
| Enrollment method and lookup | TO_FILL |
| Transport and configured trigger label | TO_FILL |
| Payload version and field/type map | TO_FILL |
| Volume units, symbol groups, UTC window | TO_FILL |
| Registration / launch cutoff and late-data policy | TO_FILL |
| Batch identity, record identity, replay rules | TO_FILL |
| Workflow and field configuration owner | TO_FILL |
| Event sender and monitoring owner | TO_FILL |
| Saved-state and reward readback | TO_FILL |
| Widget ID and supplied bundle URL | TO_FILL |
| Credential labels and rotation owner (no secrets) | TO_FILL |
| Pause, correction, and replay owner | TO_FILL |
| Test evidence and remaining joint UAT | TO_FILL |
| Launch approval | TO_FILL |

## Open decisions and approval gates

Replace TO_FILL with a named contact from each team, an agreed answer and a
non-secret evidence reference. Unassigned or unproven items remain OPEN.
An OPEN gate stops that step, not unrelated work with synthetic test data.

| Question | Accountable role | Named contact | Required answer / evidence | Blocking trigger | Status |
| --- | --- | --- | --- | --- | --- |
| Existing or ambiguous enrollment usable? | Your backend owner + Returning community owner | TO_FILL | Matched user/community, activation confirmation, recovery decision | Before minting for that user | OPEN |
| Which milestone proves completion? | Returning setup owner + your integration owner | TO_FILL | Supplied existing IDs, successful read and expected state | Before accepting the quest journey | OPEN |
| How does an open widget show new data? | Returning bundle owner + your frontend owner | TO_FILL | Bundle/version, saved state, supported refresh action and visible result | Before accepting the widget journey | OPEN |
| What if approval changes back to false? | Your rewards owner + Returning setup owner | TO_FILL | Agreed completion/reward outcome and reversal test | Before enabling the rule | OPEN |
| Downstream session and issued-token termination? | Your security lead + Returning platform owner | TO_FILL | Separate issuance, embed validation and widget-session outcomes after logout/suspension/key changes | Before security approval | OPEN |
| Bundle release, hosting and rollback? | Returning bundle owner + your release owner | TO_FILL | Approved URL/version, change notification, allowed hosting/CSP and tested rollback dependencies | Before approving bundle deployment | OPEN |
| What legacy migration is approved? | Returning setup owner + your release owner | TO_FILL | Old loader/version, identity/config mapping, cleanup dependencies, compatibility and rollback proof; agreed legacy support scope | Before cutover | OPEN |
| Which language and fallback applies? | Returning bundle owner + your frontend owner | TO_FILL | Configured bundle's available translations and tested fallback | Before locale acceptance | OPEN |
| Region, retention, export and erasure? | Returning commercial/privacy owner + your privacy lead | TO_FILL | Applicable agreement/policy reference and approved data scope | Before real customer data | OPEN |
| Limits, delays, replay, alerts and support? | Returning operations owner + your sender owner | TO_FILL | Operation-specific limits/windows, pause/correction rules, monitoring and escalation contacts/coverage | Before operational approval | OPEN |

Store actual credentials in your approved secret store.
Do not record embed tokens, API keys, or customer personal data here.
```

## Keep each kind of access in its own place

| Value | Where it belongs | What to check |
| --- | --- | --- |
| Community API key | Your backend secret store. | The intended environment/community and only the permissions the chosen operations need. |
| Widget Access ID and Access Key | Your backend secret store. | The configured widget access and allowed portal origin. These are not your community API key. |
| Workflow key and session token | Your backend, for the provisioned webhook contract. | The exact gateway, trigger, and authentication mode supplied by Returning.AI. |
| Ingest API key or AWS identity | Your sender service, for the selected transport. | Only the endpoint or provisioned queue you are allowed to send to. |
| Widget ID and bundle URL | Portal configuration; visible in the browser. | The configured experience and full environment-specific bundle URL. |
| Embed token | The authenticated browser session, for its short lifetime. | Trusted signed-in identity, refresh, and cleanup. Do not log or put it in a page URL. |

## Test the cases a happy path misses

| Case | Expected safe behavior | Guide |
| --- | --- | --- |
| User already exists or create response times out | Use the supported lookup and reconcile membership. Do not create repeatedly or merge unrelated users. | [Enrollment](https://docs.returning.ai/broker-integrations/users.md) |
| Activity arrives before enrollment | Hold or reconcile the unmatched activity according to the agreed workflow policy. Do not silently award another user. | [Account mapping](https://docs.returning.ai/broker-integrations/users.md) |
| Invalid field type, zero, or false | Validate against the field and endpoint contract. Do not turn a valid zero/false into missing input. | [User fields](https://docs.returning.ai/broker-integrations/user-fields.md) |
| Field saved but milestone unchanged | Inspect the configured condition, evaluation, and result separately from the field write. | [Milestones](https://docs.returning.ai/broker-integrations/user-fields.md) |
| Exact retry, changed payload, or partial failure | Use the configured replay identity and inspect per-record results. A new batch ID is not automatically a safe correction. | [Ingest and replay](https://docs.returning.ai/broker-integrations/sqs.md) |
| Unknown symbol/account or late trade | Apply the agreed mapping and late-data policy. Preserve original time and source identity; do not guess eligibility. | [Volume and rewards](https://docs.returning.ai/broker-integrations/trading-rewards.md) |
| Referral signup succeeds but attribution is absent | Verify the relationship independently. Do not repeat user creation or assume a reward was issued. | [Referrals](https://docs.returning.ai/broker-integrations/referrals.md) |
| Expired session, logout, or user switch | Fetch a token from the trusted current session, update the existing widget when appropriate, and remove the old user view on sign-out. | [Widget troubleshooting](https://docs.returning.ai/widget-sdk/troubleshooting.md) |

## The sender succeeded. Why is the widget unchanged?

1. **Check identity and environment.** Does the event target the same registered user and community as the widget token?
2. **Check the transport receipt.** Keep the event/batch identity and non-secret response. For batch APIs, inspect individual results even if the HTTP response was successful.
3. **Ask Returning.AI to check ingest and workflow execution.** Confirm validation, routing, user mapping, and node outputs. The workflow editor test is not proof that your sender delivered a real event.
4. **Check any queued user update.** A workflow can finish before its bulk job. Returning.AI checks the job and affected rows, including partial failures.
5. **Read saved values and reward state.** Use the supported user/field readback for your integration. Confirm the configured rule actually qualifies this event.
6. **Check the widget session and view.** Only after saved state is correct, check token identity, session freshness, and the widget's data refresh behavior.

> Do not replay an award to refresh the screen
>
> If the saved balance is already correct, another additive award can duplicate the reward. Fix the display or session path instead. If a write outcome is unclear, reconcile authoritative state before deciding whether to retry.

## Agree who can pause and recover the feed

Name the sender owner who monitors delivery errors and maintains stable event identity, and agree the Returning.AI owner for the configured consumer, workflows, queued updates and unmatched records. Confirm who reviews queue age, backlog, failed rows and unexpected reward totals; this checklist does not create a monitoring or response-time commitment.

Before launch, name the person who can pause new submissions and the person who approves corrections or replay. Keep successful users out of a failed-row replay. Preserve source facts and checkpoints so recovery does not require guessing what was already applied.

Use [the integration map](https://docs.returning.ai/broker-integrations.md) to return to the missing step, or [the widget quickstart](https://docs.returning.ai/widget-sdk.md) when the backend checks pass.