セットアップと前提条件
サーバー Firewall 設定の前提条件
連携を進める前に、Unifi サーバーとの適切な通信および API 呼び出し（ユーザーマッピング確認、登録、ミッション達成など）を確実に行うため、バックエンドで以下の Firewall 設定と認証キー設定を完了しておく必要があります。
- サーバー IP の登録（Firewall 開放）: お客様のサービスサーバーから Unifi サーバーへ API を呼び出せるようにするため、お客様の IP を Unifi の Firewall に Whitelist 登録する必要があります。連携を開始する前に、サービスサーバーのすべての Outbound IP アドレスを Unifi 担当者に提供してください。
- 認証キーの設定: 事前に Unifi 担当者から
X-Partner-IdおよびX-Api-Keyを取得し、API 呼び出しのリクエストヘッダーに含められるよう、バックエンドの環境変数に設定してください。
Unifi システム登録のための事前提供情報
お客様のサービスを Unifi のミッション・報酬システムに掲出するには、連携開発の前に以下の企画情報およびアセットを整理し、Unifi 担当者へ提供する必要があります。
Partner（サービスパブリッシャー）基本情報
- メイン URL: 貴社またはサービスのメインウェブサイトのアドレス。
- ロゴ画像: 420 × 420 ピクセル。Partner を代表する画像です。
- スクリーンショット画像: 600 × 1296 ピクセル（最大 7 枚）。Partner を紹介する画像で、ミッションページの Preview 領域に表示されます。
- 多言語 Partner 名: 英語（EN）は必須です。その他の言語は任意です。
- 多言語 Partner タイトル（ショート説明）: Partner を紹介する短い説明です。5 言語（EN, KR, JA, TH, TW）での提供が必須です。
- 多言語 Partner 詳細説明: Partner についてユーザーに伝えたい追加情報があれば記載してください。5 言語（EN, KR, JA, TH, TW）での提供が必須です。
- 公式ソーシャルチャンネル（OA）: 公式ソーシャルチャンネル（LINE, X, Facebook, Discord, Instagram, Medium）へのリンク。
- Tag: サービスに関連するキーワード（例：
#puzzle、#RPG）。Partner の説明と併せて表示されます。
各項目が実際にどの位置に表示されるかは、下記のラベル付き画面をご参照ください。
Mission Group（サービスマッチング）基本情報
- 多言語タイトル＆紹介文: Unifi アプリのミッション一覧に表示されるタイトルおよび紹介テキスト。5 言語（EN, KR, JA, TH, TW）での提供が必須です。
- メインバナー画像: 1280 × 720 ピクセルの画像 1 枚。ミッションページに入場した際に表示されます。
- マッチングする Service ID: この Mission Group と紐付けるお客様のサービスの一意の識別子。
- ミッション掲出方式: 現在は「全掲出（リスト形式）」方式で運用されており、登録されたすべてのミッションを一度に表示します。（単一ミッションの場合は自動的に「全掲出」が選択されます）
- 最終クリア条件: グループ全体を達成とみなすために完了が必要な、グループ内の Individual Mission の目標数を設定します。（単一ミッションの場合は自動的に 1 に設定されます）
- ミッション注意事項（任意）: Mission Group に多言語で注意事項を記載すると、App Detail Page に表示されます（例：「この報酬は日本のユーザーのみが対象です」）。未記載の場合、テキストは表示されません。
Individual Mission 詳細と Mission Key 発行方法
Unifi に登録される各 Individual Mission には、API 識別用の Mission Key があります。開発の利便性に応じて、以下の 2 つの方法から選択できます。
- Unifi ランダム生成: Unifi システムがランダムな英数字キーを生成し、お客様に提供します。
- Partner 既存 ID マッピング: お客様のサービスサーバーで管理している既存のミッション/達成 ID（Mission ID）を提供いただき、それをそのまま Unifi システムの Mission Key として登録します。別途マッピング値を管理する必要がなくなるため、開発の利便性が向上します。
ヒント
Mission Key 重複禁止ポリシー
生成方法や Partner ID 登録の如何にかかわらず、同一サービス（Service ID）内で Mission Key を重複させることは決してできません。
Mission Key は、達成情報を受け取るために事前に Unifi と共有しておく必要があり、共有済みのキーで情報が届いた場合にのみ報酬が処理されます。達成情報の連携 API については API 仕様をご参照ください。
- Mission Type Name: ミッションの性質を示す一意の英語キーワード（例：PLAY, ACHIEVE_LEVEL）。
- 多言語ミッション名: ユーザーに表示される実際のミッション目標テキスト。5 言語（EN, KR, JA, TH, TW）での提供が必須です。
- ミッションサムネイル画像（任意）: 400 × 400 ピクセル（未提供の場合はデフォルト画像に置き換えられます）。
- Mission Link（遷移 URL）: Unifi アプリでユーザーがミッションをクリックした際に遷移する、お客様のサービス URL。接続環境ごと（LIFF / Web / Mini）にご用意ください — 該当環境の URL がない場合、その環境ではミッションが表示されません。
報酬構成
報酬方式
MINI Partner は、以下 2 つの方式のいずれかを選択します。
| 方式 | 説明 | 設定単位 |
|---|---|---|
Fixed（FIXED） | ミッション達成時に、設定された JPYC 数量をそのまま支払います。 | 報酬数量 |
Lucky Draw（LUCKY_DRAW） | ミッション達成時に抽選券を付与し、ユーザーが抽選を行うことで報酬が変動します。 | 抽選券の枚数 |
- Reward Unit: Individual Mission クリア時 / Mission Group クリア時のいずれで報酬を付与するかを選択します。
予算と報酬額の設定
- ミッション全体の予算は、ミッション開始の 2 週間前までに協議します。複数のミッションを運用する場合、合意した全体予算を各ミッションに配分して設定できます。
- 個別の報酬額は方式によって設定内容が異なります。
- Fixed: 1 回あたりに支払う数量
- Lucky Draw: 付与する抽選券の枚数
- ユーザーごとの最大報酬額は任意項目で、Fixed・Lucky Draw のどちらにも設定できます。設定しない場合、上限はありません。
- Lucky Draw では、全体予算に加えて等級ごとの報酬額・当選者数（当選確率の構成）まで決めておく必要があるため、事前に Unifi ビジネスチームとご協議ください。
予算が尽きた場合
報酬予算を使い切るか、設定した上限に達すると、その報酬に紐付いたミッションまたは Mission Group は自動的に終了します。運用状況によっては、予定より早く終了する場合があります。
運用チェックリスト
ミッション運用中は、以下の点にご注意ください。
- Partner 情報の事前登録: ミッションページには Partner 情報も併せて表示されるため、ミッションを設定する前に Partner 情報が登録されている必要があります。
- Mission Key の事前共有: 事前に共有されていない場合、達成情報をミッションに紐付けられず、報酬も支払われません。
- ワンタイムミッションの重複支給防止: ワンタイムミッションは、達成情報を複数回受信しても報酬は 1 回のみ支払われます。繰り返し報酬を付与したい場合は、事前に Unifi 担当者とご相談ください。
- ミッションの開始・終了時刻: 分単位まで設定可能です。
ヒント
ミッション達成 API など技術連携に関するご質問は、API 仕様のご案内をご参照ください。