Streaks and embeds

Contract source

This page summarizes the approved architecture in docs/architecture/ (ADR-0006) and rewardos-backend/contracts/openapi/b2b-v1.yaml. Prefer those sources if anything diverges from older portal scaffolding.

Overview

RewardOS hosts the streak UI. Your server mints a 60-minute embed URL with your API key; your app opens that URL in a WebView/iframe. Check-ins are recorded from your server, not from the WebView.

Partner APIs

Method	Path	Purpose
POST	/b2b/embeds/streak	Mint { embedUrl, expiresAt, sessionId } for externalUserId
GET	/b2b/streaks/{externalUserId}	Read streak + reward history
POST	/b2b/streaks/{externalUserId}/check-in	Authoritative daily check-in

Authenticate with x-api-key (same as other B2B routes).

WebView events

The hosted page posts:

{ "source": "rewardos", "type": "rewardos:ready", "payload": { "version": 1 } }

Events: rewardos:ready, rewardos:streak_updated, rewardos:reward_claimed, rewardos:error, rewardos:resize.

Full snippets: architecture guide docs/architecture/b2b-streak-embed-integration.md.

Rewards

Milestone check-ins can grant coupon/offer entitlements. Users revisit the embed to claim earned rewards; your server can also read entitlement history via GET /b2b/streaks/{externalUserId}.