FIZOR DOCUMENTATION
Ad Rewards
Ad Rewardsは、設定した広告checkpointの完了後にKeyを発行または延長します。provider callbackだけがcheckpointを完了でき、browser redirectやstate文字列だけでは進行しません。
利用の流れ
POST /api/rewards/{programId}/sessionでsessionを開始します。期限延長Programではkeyが必須です。Allow Extendingが有効なkey発行Programでは、keyを渡すと既存key延長として処理します。X-Reward-Session-Token付きのGET /api/rewards/{sessionId}/checkpointsからauthorizeUrlを取得します。- providerが
POST /api/rewards/providers/fizor_hmac_v1/callbackへ完了eventを送信します。 - 全checkpoint後、
POST /api/rewards/{sessionId}/claimで付与を確定します。 - callback欠落時は
POST /api/rewards/{sessionId}/reconcileでproviderへ再照合できます。
callbackはevent_id、provider認証済みの安定したsubject_id、署名済みstate、status: completedを含みます。X-Fizor-Reward-TimestampとHMAC-SHA256(REWARD_PROVIDER_SECRET, timestamp + "." + rawBody)であるX-Fizor-Reward-Signatureが必須です。timestamp許容差は±300秒です。
session token、nonce、event ID、client IPはHMAC値だけを保存し、raw callbackや署名は保存しません。同一eventは冪等で、異なるpayloadへの再利用は拒否します。
管理画面では、Reward Programごとにproviderとcheckpointを設定します。
Reward Name: visitorに見えるreward名Key Duration (hours): 完了後に発行・延長する時間Max Keys: 同じvisitorが同時に保持できるactive reward key数Allow Extending: 新規key発行Programでも既存key延長を許可Cooldown (hours): 再完了までの待機時間Allow Forgetting: visitor側のbrowser/session解除許可を示す設定Max Hours: 延長後に保持できる最大時間Block Incognito、Block VPNs、Require Discord OAuth2、Blocked Countries: provider/visitor UI側の品質制御用設定
checkpointは短時間で期限切れになります。FizorではsessionTtlSecondsを最大4200秒、つまり約70分に制限しています。
provider URLはHTTPSを使用します。Short URL、Work.ink Link ID、callback URL、token、Postback placeholderは機械値としてそのままコピーしてください。