正在載入搜尋…

正在載入搜尋…

跳至內容
行銷活動免費商品

免費道具

讓玩家無需輸入代碼或付款即可領取活動獎勵。您的伺服器查詢活動狀態、為接收者提交領取請求,再處理 redemption.completed Webhook,在遊戲中發放獎勵。

完整的請求與回應結構請參閱免費道具 API 參考。

身份驗證與接收者識別碼

從伺服器使用金鑰呼叫 API。查詢狀態需要 FreeItemStatus 許可權,領取需要 FreeItemClaim 許可權。金鑰只儲存在後端,recipientId 應來自遊戲中已登入並通過身份驗證的玩家。

recipientId 是您自己系統中接收者(即接收獎勵的帳號)的識別碼。Tokenz 不會查詢遊戲帳號,只根據這個字串識別接收者。

  • 會去除首尾空白,不允許空白值。
  • 最多 100 個字元。超長值會返回 request.decoding-failed,不會被截斷。
  • 區分大小寫。Player_123 和 player_123 是不同的接收者,各有獨立額度。
  • 所有呼叫都應使用同一個穩定識別碼,不要轉為小寫或通過其他方式合併不同識別碼。
  • 相同識別碼在不同裝置、會話或店面中共享領取額度。

活動設定與狀態

在 Tokenz Dashboard 中配置活動時間、獎勵、活動總額度、每位接收者的額度以及重複週期,並管理暫停、恢復和結束操作。如果看不到免費道具設定,請聯絡 Tokenz 支援,確認您的帳號是否已開放此功能。

  • draft:草稿,不能領取,所有欄位可編輯。
  • scheduled:已釋出,等待開始;到達 startAt 即可領取。
  • active:活動進行中,可以領取。
  • paused:已暫停,不能領取,可恢復為 active。
  • ended:已結束,不能領取,此狀態不可撤銷。

查詢與領取要求活動類型為免費道具,狀態為 active,或為 scheduled 且已到達 startAt,並且尚未到達 endAt。即使儲存的狀態尚未更新,已到開始時間的 scheduled 活動也可使用。時間按絕對時刻比較,玩家所在地不會改變活動結束時刻。

額度與重複週期

每次領取都會檢查兩個獨立的額度:

  • 活動總額度:所有接收者的領取次數總和。達到上限後返回 campaign.limit-reached。
  • 每位接收者的額度:同一 recipientId 的領取次數。一次性活動達到上限返回 campaign.recipient-limit-reached;重複活動返回 campaign.recipient-period-limit-reached。其他接收者不受影響。

一次性活動的兩個額度均適用於活動整個生命週期,不會重置。重複活動的兩個額度都會在每個週期開始時重置。被拒絕的領取不會消耗任一額度。

可視需要左右捲動
頻率週期開始時間
一次性不重置
每日當地時間午夜
每週週一當地時間午夜
每月每月第一天當地時間午夜

使用活動的時區,而非玩家時區。API 不返回該時區,因此不要自行計算週期邊界。使用 nextResetAt 顯示倒計時,到達該時刻後重新查詢狀態。該時刻及之後的領取屬於新週期。重置不會延長 endAt。

例如,每日活動總額度為 100 次、每位接收者限 1 次,則每天最多 100 位接收者各領取一次。次日重置後,總額度恢復到 100 次,前一天已領取的接收者也可再次領取。

領取流程

  1. 在自己的系統中儲存 campaignId。
  2. 伺服器呼叫 GET /v3/free-items/{campaignId}?recipientId=...,顯示獎勵與剩餘額度。
  3. 玩家點選領取後,伺服器呼叫 POST /v3/free-items/claim。
  4. Tokenz 建立領取記錄,返回 201,並發送 redemption.completed Webhook。
  5. 後端驗證簽名,使用 redemptionId 防止重複發放,再發放獎勵。

查詢狀態

campaignId 是必需的路徑引數,recipientId 是可選的查詢引數。狀態查詢不會預留額度,提交領取時可用額度可能已改變。額度耗盡時,狀態介面返回剩餘次數 0,而不是額度錯誤。

bash
curl --request GET \
  --url 'https://api.tokenz.one/v3/free-items/campaign_1p4LPTRKB5Z_t?recipientId=player_98765' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

成功回應(200)

json
{
  "campaign": {
    "id": "campaign_1p4LPTRKB5Z_t",
    "name": "Weekly Free Pack"
  },
  "rewardPreview": {
    "name": "Marathon Energy Gift",
    "imageUrl": "https://images.example.com/rewards/energy.png",
    "quantity": 1
  },
  "campaignRemaining": 842,
  "remainingForRecipient": 1,
  "nextResetAt": "2026-09-14T00:00:00Z"
}
  • campaignRemaining:所有接收者可用的剩餘次數。重複活動為當前週期,一次性活動為整個生命週期。未設定活動總額度時省略。
  • remainingForRecipient:此接收者的剩餘次數。未提供 recipientId 或未設定每位接收者的額度時省略。
  • nextResetAt:兩個額度下次重置的絕對時刻。一次性活動省略。

領取免費道具

請求主體中的 campaignId 和 recipientId 均為必填項。活動必須可領取,且兩個額度都未耗盡。API 建立記錄;實際獎勵由您的後端處理 Webhook 時發放。

bash
curl --request POST \
  --url https://api.tokenz.one/v3/free-items/claim \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Idempotency-Key: claim_player_98765_2026-09-10T08:10:00Z_a1b2c3d4' \
  --data '{
    "campaignId": "campaign_1p4LPTRKB5Z_t",
    "recipientId": "player_98765"
  }'

成功回應(201)

json
{
  "redemption": {
    "redemptionId": "redemption_1p4LPTRKB5Z_t",
    "recipientId": "player_98765",
    "campaign": {
      "id": "campaign_1p4LPTRKB5Z_t",
      "name": "Weekly Free Pack"
    },
    "reward": {
      "skuRedemptionReward": {
        "type": "EXTERNAL_SKU",
        "sku": "ITEM_ENERGY_GIFT",
        "name": "Marathon Energy Gift",
        "quantity": 1
      }
    },
    "redeemedAt": "2026-09-10T08:10:00Z",
    "kind": "FREE_ITEM_CLAIM",
    "source": "FREE_ITEM_CLAIM",
    "nextPeriodStart": "2026-09-14T00:00:00Z"
  },
  "remainingForRecipient": 0,
  "nextResetAt": "2026-09-14T00:00:00Z"
}

remainingForRecipient 是本次領取後的剩餘次數,未設定每位接收者的額度時省略。一次性活動省略 nextResetAt。redemption 物件欄位與下方 Webhook 相同。

Webhook 與獎勵發放

Tokenz 向訂閱此事件的端點發送 redemption.completed,與禮品碼(原名為兌換碼)兌換使用同一事件。

發放獎勵前先驗證 Tokenz-Signature。 針對原始請求主體驗證,再解析內容。跳過驗證會使偽造請求獲得獎勵。請參閱保護你的 webhook 端點。

json
{
  "id": "f75ff6f0-bdf9-4b25-bb96-968f8733a7e3",
  "object": "redemption.completed",
  "createdAt": "2026-09-10T08:10:00Z",
  "test": true,
  "eventData": {
    "type": "redemption",
    "version": "v3",
    "data": {
      "redemption": {
        "redemptionId": "redemption_1p4LPTRKB5Z_t",
        "campaign": {
          "id": "campaign_1p4LPTRKB5Z_t",
          "name": "Weekly Free Pack"
        },
        "recipientId": "player_98765",
        "reward": {
          "skuRedemptionReward": {
            "type": "EXTERNAL_SKU",
            "sku": "ITEM_ENERGY_GIFT",
            "name": "Marathon Energy Gift",
            "quantity": 1
          }
        },
        "redeemedAt": "2026-09-10T08:10:00Z",
        "kind": "FREE_ITEM_CLAIM",
        "source": "FREE_ITEM_CLAIM",
        "nextPeriodStart": "2026-09-14T00:00:00Z"
      }
    }
  }
}
  • kind:免費道具為 FREE_ITEM_CLAIM,禮品碼為 CODE_REDEMPTION。新事件都會設定此欄位,但較早進入佇列的事件可能省略。
  • source:已棄用,僅為相容現有整合保留。新整合使用 kind。
  • code:僅禮品碼兌換包含此欄位,免費道具領取會省略。請檢查現有處理程序是否錯誤地要求其存在。
  • nextPeriodStart:僅重複免費道具活動包含。它根據 redeemedAt 時的活動週期計算下一週期開始時刻,而非根據 Webhook 投遞時間計算。一次性領取和禮品碼兌換均省略。

通常只需根據 redemptionId、recipientId 和 reward 共用一套發放邏輯。kind 缺失或未知時不要猜測類型,仍使用這三個欄位發放,並標記事件以供核對。頂層事件 id 用於追蹤投遞,redemptionId 用於防止重複發放。

冪等與重試

在 POST /v3/free-items/claim(v1 同樣適用)上傳送可選的 Idempotency-Key 請求標頭,不要放在 JSON 請求本體中。每次新的領取嘗試應產生新值(例如玩家點擊領取時);僅在網路錯誤、逾時或回應遺失後重試同一次嘗試時複用同一值。

省略 Idempotency-Key 時行為與舊版整合一致:額度允許時,每次成功請求都可能再建立一條領取記錄。沒有該標頭時不要盲目重試。

提供該標頭時,僅當 campaignId 與 recipientId 與首次請求一致才會回放已有領取;同一鍵用於不同活動或接收者時視為新的領取。若已有領取,Tokenz 回傳 201 及原 redemptionId,不會再次消耗額度。

Webhook 處理仍應依 redemptionId 去重;Webhook 去重不能代替領取請求的冪等標頭。

Webhook 投遞重試

端點未接受 Webhook 時,Tokenz 會逐漸增加間隔並加入隨機變化進行重試。重試安排在首次嘗試後的最長 72 小時視窗內;這不是保證在視窗內送達,實際執行可能延後。不要依賴固定次數或準確時間。投遞可能晚到數天,因此應將已發放的 redemptionId 持久儲存,而非放入短期快取,並保證同一 ID 的獎勵只發放一次。

錯誤處理

  • 400 / request.decoding-failed:無效 ID、空白或超長的 recipientId、空白或超長的 Idempotency-Key,或格式錯誤的請求。
  • 401:缺少或無效的 API 金鑰。
  • 403:缺少所需許可權。
  • 404 / entity.not-found:活動不存在、屬於其他商戶,或測試模式與金鑰不匹配。
  • 422 / campaign.kind-invalid:不是免費道具活動。
  • 422 / campaign.status-invalid:草稿、暫停、結束,或尚未開始的預定活動。
  • 422 / campaign.expired:已到結束時刻;結束狀態也可能返回 campaign.status-invalid。
  • 422 / campaign.limit-reached:總額度耗盡;重複活動為當前週期,一次性活動為整個生命週期。
  • 422 / campaign.recipient-limit-reached:每位接收者的額度耗盡。
  • 422 / campaign.recipient-period-limit-reached:當前週期的每位接收者額度耗盡,可在 nextResetAt 後重試。
  • 429:超過速率限制。兩個介面均按 API 金鑰限制;提供接收者識別碼時,也按接收者限制。
  • 500:意外的伺服器錯誤。

測試

使用以 secret_test_ 開頭的金鑰,在 Dashboard 測試模式下建立活動。測試與正式資料隔離,金鑰只能操作模式匹配的活動。測試 ID 以 _t 結尾;測試 Webhook 僅傳送到測試端點,承載內容包含 "test": true。

測試成功領取與獎勵發放、兩個額度耗盡、週期重置、暫停與過期、重複投遞,以及使用相同 Idempotency-Key 重試並返回相同 redemptionId 的情況。也應驗證空白和超長 recipientId、速率限制以及測試與正式模式隔離,並確認每個 redemptionId 只發放一次獎勵。