Referral Tracking

APIエンドポイント

サーバーサイドの紹介トラッキングエンドポイント

紹介APIエンドポイント

サーバーサイドの紹介トラッキングを好む場合（またはバックエンドのみの統合に必要な場合）、JavaScriptトラッキングスクリプトを使用する代わりにこれらのエンドポイントを直接呼び出すことができます。

すべての紹介エンドポイントはCORSをサポートしており、APIキー認証は不要です。

紹介キャンペーンとアフィリエイトキャンペーンの違い: 紹介キャンペーンはサインアップと購入時にポイントを付与します。アフィリエイトキャンペーンは、独自の支払い構造を用いて紹介された購入に対してドルのコミッションを付与します — 販売の割合か販売ごとの固定額のいずれか（両方ではありません）。サインアップトラッキングはアフィリエイトキャンペーンではコミッションを支払いません（購入のみ）。購入のレスポンスには紹介モード用のpointsAwardedとアフィリエイトモード用のcommissionAwardedが含まれます。

紹介コードの検証

GET/api/referral/validate-code
No authentication required

紹介コードが有効かどうかを確認し、紹介者に関する情報を取得します。

クエリパラメータ

codestring required

検証する紹介コード

contestIdstring required

コンテスト識別子

リクエスト

bash
curl -X GET "https://blitzrocket.com/api/referral/validate-code?code=REF-XYZ789&contestId=clx1abc123"

レスポンス

json
{
  "valid": true,
  "referrerEmail": "jane@example.com",
  "referrerName": "Jane Doe",
  "contestId": "clx1abc123"
}

訪問のトラッキング

POST/api/referral/track-visit
No authentication required

誰かが紹介リンクを通じてあなたのサイトを訪問したことを記録します。

リクエストボディ

referralCodestring required

URLからの紹介コード

contestIdstring required

コンテスト識別子

urlstring

訪問したページのURL（任意）

リクエスト

bash
curl -X POST https://blitzrocket.com/api/referral/track-visit \
  -H "Content-Type: application/json" \
  -d '{
    "referralCode": "REF-XYZ789",
    "contestId": "clx1abc123",
    "url": "https://yoursite.com/landing-page"
  }'

レスポンス

json
{
  "success": true
}

サインアップのトラッキング

POST/api/referral/track-signup
No authentication required

紹介された訪問者がサインアップしたことを記録します。

リクエストボディ

emailstring required

新規サインアップのメールアドレス

contestIdstring required

コンテスト識別子

referralCodestring

紹介者の紹介コード（直接サインアップの場合は任意）

externalSiteUrlstring required

サインアップが行われたページのURL

namestring

新規サインアップ者の名前（任意）

リクエスト

bash
curl -X POST https://blitzrocket.com/api/referral/track-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "campaignId": "clx1abc123",
    "referralCode": "REF-XYZ789",
    "externalSiteUrl": "https://yoursite.com/signup"
  }'

レスポンス

json
{
  "success": true,
  "data": {
    "entryId": "entry_new789",
    "isReferred": true,
    "pointsAwarded": {
      "advocate": 10,
      "friend": 5
    }
  }
}

購入の追跡

POST/api/referral/track-purchase
No authentication required

紹介されたユーザーが購入を行ったことを記録します。blitzrocket.js の RocketTracker.trackPurchase() で使用されます。

リクエストボディ

campaignIdstring required

コンテスト識別子（contestId と同じ）

referralCodestring required

紹介者のリファラルコード

orderIdstring required

一意の注文識別子

amountnumber required

購入金額

externalSiteUrlstring required

購入が行われたページのURL

emailstring

購入者のメールアドレス（任意）

phonestring

購入者の電話番号（任意）

currencystring

通貨コード（デフォルト: 'USD'）

リクエスト

bash
curl -X POST https://blitzrocket.com/api/referral/track-purchase \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "clx1abc123",
    "referralCode": "REF-XYZ789",
    "orderId": "order-12345",
    "amount": 99.99,
    "currency": "USD",
    "externalSiteUrl": "https://yoursite.com/checkout/success",
    "email": "buyer@example.com"
  }'

レスポンス

リファラルキャンペーン（ポイント）:

json
{
  "success": true,
  "message": "Purchase tracked successfully",
  "referrerEntryId": "entry_abc123",
  "pointsAwarded": { "advocate": 50, "friend": 10 },
  "commissionAwarded": { "advocate": 0 }
}

アフィリエイトキャンペーン（ドルコミッション）:

json
{
  "success": true,
  "message": "Purchase tracked successfully",
  "referrerEntryId": "entry_abc123",
  "pointsAwarded": { "advocate": 0, "friend": 0 },
  "commissionAwarded": { "advocate": 24.99 }
}

メールのみでの購入追跡（リクエストにリファラルコードがない場合）は、代わりに POST /api/contest/track-purchase を使用してください。

完全なサーバーサイドの例

サーバー上でリファラルトラッキングを実装する完全な例を示します。

javascript
const express = require("express");
const app = express();

const BLITZROCKET_BASE = "https://blitzrocket.com/api/referral";
const CONTEST_ID = process.env.CONTEST_ID;

app.post("/api/signup", async (req, res) => {
  const { email, name, referralCode } = req.body;

  // 1. システム内でユーザーを作成する
  const user = await createUser({ email, name });

  // 2. Blitz Rocketで紹介によるサインアップをトラッキングする
  if (referralCode) {
    await fetch(`${BLITZROCKET_BASE}/track-signup`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        email,
        name,
        contestId: CONTEST_ID,
        referralCode,
      }),
    });
  }

  res.json({ success: true, user });
});

app.post("/api/purchase", async (req, res) => {
  const { email, orderId, amount, currency } = req.body;

  // 1. システム内で購入処理を行う
  const order = await processOrder({ email, orderId, amount });

  // 2. Blitz Rocketで購入をトラッキングする
  await fetch(`${BLITZROCKET_BASE}/track-purchase`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email,
      contestId: CONTEST_ID,
      orderId,
      amount,
      currency,
    }),
  });

  res.json({ success: true, order });
});