クーポンAPI仕様

概要

RoktのクーポンAPIは、Rokt広告クライアントがキャンペーンで使用するためのプロモーションクーポンコードにシームレスにアクセスして取得できるようにします。クーポンはRoktシステムで管理され、Rokt広告の顧客コンバージョン時に管理されます。

認証

RoktのクーポンAPIにアクセスするためのAPIキーを作成するには、Roktのアカウントマネージャーに連絡してください。APIはbase64エンコードされたベアラ認証を利用します。APIキーには多くの特権があるため、安全に保管してください！GitHubやクライアントサイドコードなどの公開されている場所で秘密のAPIキーを共有しないでください。

APIリファレンス

クーポンAPIは、クーポン管理のためにRoktクリエイティブに紐付けられたクーポンとRoktセッションIDを必要とします。セッションIDは、特定のクーポンコードの配布を最大1回に制限するために必要です。アカウントIDが不明な場合は、アカウントマネージャーに連絡してください。詳細はキー要件セクションに記載されています。

エンドポイントURL	http://coupon-api.rokt.com/api/v1

リクエスト

POST /accounts/{account_id}/creative/{creative_id}/session/{session_id}/allocate-coupon

ヘッダー

名前	値	必須	説明
Content-Type	application/json	はい	N/A
Charset	utf-8	はい	N/A
Authorization	Bearer base64(rokt-coupon-key:{secretValue})	はい	Bearer認証ヘッダーで、資格情報の値は文字列"rokt-coupon-key"とシークレット値をコロンで結合したものをbase64エンコードしたもの

パラメーター

名前	必須	型	場所	説明
accountId	はい	文字列、最大64文字	パス	RoktアカウントID
creativeId	はい	Long	パス	顧客がオプトインしたクリエイティブのRokt内部識別子
sessionID	はい	文字列、最大64文字	パス	パートナーからのトラフィックURLの一部として渡されるRoktセッションID

リクエスト例

curl -X POST http://coupon-api.rokt.com/api/v1/accounts/3284705019915440561/creative/1/session/1/allocate-coupon \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {YOUR_ENCODED_TOKEN}" \
-d '{}'

レスポンス例

{
  "couponId": "67c41952-55b5-4fca-8fe8-8da4116ded3e",
  "couponCode": "COUPON-CODE-475558",
  "accountId": "3284705019915440561",
}

エラーハンドリング

例外	HTTP コード	原因	解決策
AuthorizationHeaderMissing	401 Unauthorized	リクエストにAuthorizationヘッダーがありません。	リクエストに有効なAuthorizationヘッダーを含めてください。
AuthenticationFailure	401 Unauthorized	無効なAPIキー、期限切れのトークン、または不正な認証情報。	有効な認証情報を提供してください。
InvalidAuthorizationHeaderFormat	401 Unauthorized	Authorizationヘッダーの形式が不正です（例：Bearerが欠落している、またはトークンが不正）。	ヘッダーが正しい形式に従っていることを確認してください。例：Authorization:Bearer base64(rokt-coupon-key:{secretValue})
FailedToRetrieveSecrets	401 Unauthorized	Authorizationヘッダーの形式が無効です（トークンが不正またはシークレットから欠落しています）。	Authorizationヘッダーの形式を確認してください。
InvalidToken	401 Unauthorized	提供されたトークンが無効、期限切れ、または取り消されています。	新しいトークンをリクエストし、使用前に有効であることを確認してください。
FailedToValidateCouponPayload	400 Bad Request	クーポンリクエストペイロードに無効または欠落しているフィールドがあります。	すべての必須フィールドが含まれており、送信前に正しくフォーマットされていることを確認してください。
FailedToAllocateCoupon	500 Internal Server Error	クーポンを割り当てようとした際にサーバーが問題に遭遇しました。	このエラーはCoupon APIまたはその基盤サービスに問題があるため発生しました。Roktサポートチャンネルに連絡してください。
NoCouponsRemaining	404 Not Found	このオファーのクーポンが残っていません。	クーポンリストを補充するためにRoktのアカウントマネージャーに連絡してください。

主な要件

Rokt Coupon APIからクーポンコードを取得するには、以下のパラメータが必要です：

• アカウントID
• クリエイティブID
• セッションID

アカウントIDは一定の値ですが、Roktはクリエイティブの宛先URLを通じてセッションIDとクリエイティブIDを提供します。これを行う方法の詳細は以下に記載されています。

広告主統合のデータフロー

1. トラフィックURLからパラメータを抽出する: ユーザーが広告主のページにリダイレクトされると、トラフィックURLには必要なパラメータが含まれます。たとえば、クリエイティブには次のようなトラフィックURLが含まれることがあります: https://samplewebsite.com/download?sessionid=abcdef123456&creativeid=67890。セッションIDはUUIDで、クリエイティブIDはbigintです。

2. パラメータをローカルストレージに保存する: 広告主はURLを解析し、セッションIDとクリエイティブIDをブラウザのローカルストレージまたは選択した別の方法で安全に保存する必要があります。抽出と保存のための以下のコードスニペットを参照してください:

const urlParams = new URLSearchParams(window.location.search);
const sessionid = urlParams.get('sessionid');
const creativeid = urlParams.get('creativeid');

if (sessionid && creativeid) {
    localStorage.setItem('sessionid', sessionid);
    localStorage.setItem('creativeid', creativeid);
}

3. 保存されたパラメータをRokt Coupon APIに渡す: Rokt Coupon APIを呼び出す際に、ローカルストレージから保存されたパラメータを取得し、APIリクエストボディに含めます。APIを呼び出すための以下のコードスニペットを参照してください:

注記

アカウントID、認証トークン、その他の機密情報はコードに直接保存しないでください。この例はデモンストレーション目的のみです。

// トラフィックURLからパラメータを抽出する
const urlParams = new URLSearchParams(window.location.search);
const sessionid = urlParams.get('sessionid');
const creativeid = urlParams.get('creativeid');
const accountid = 'YOUR_ACCOUNT_ID'; // あなたのRoktアカウントIDに置き換えてください

// パラメータをローカルストレージに保存する
if (sessionid && creativeid) {
    localStorage.setItem('sessionid', sessionid);
    localStorage.setItem('creativeid', creativeid);
}

// 保存されたパラメータをAPI呼び出しで渡す
const storedSessionId = localStorage.getItem('sessionid');
const storedCreativeId = localStorage.getItem('creativeid');

if (storedSessionId && storedCreativeId && accountid) {
```javascript
// パラメータをパスに含めてAPI URLを動的に構築する
const apiUrl = `http://coupon-api.stage.rokt.com/api/v1/accounts/${accountid}/creative/${storedCreativeId}/session/${storedSessionId}/allocate-coupon`;

fetch(apiUrl, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${authToken}` // authTokenをAPIキーに置き換えてください
    },
    body: JSON.stringify({}) // 必要に応じて空のJSONボディ
})
.then(response => {
    if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
})
.then(data => {
    console.log('クーポンコード:', data.code);
})
.catch(error => console.error('エラー:', error));
} else {
    console.error('必要なパラメータが不足しています。');
}