ここでは仮想通貨の自社サーバで管理される場合の実装方法を説明します。
この方法はユーザの仮想通貨をより便利にコントロールできますが、自社サーバで完全な責任ですべての仮想通貨を管理しなければなりません。仮想通貨のTapjoy管理で利用されているgetTapPoints, awardTapPoints, spendTapPointsメソッドは自社管理時には利用してはいけません
Table of Contents
コールバックURL
ユーザーが広告のアクションを完了して仮想通貨を獲得すると、TapjoyサーバーがHTTPリクエストを送信します。 パラメーターのフォーマットは次のようになります。
<callback_url>?snuid=<user_id>& currency=<currency>&mac_address=<mac_address>&display_multiplier=<display_multiplier>
デフォルトのリクエストパラメーターには、
- snuid:ユーザID(詳細はユーザーIDを参照してください)
- currency:ユーザーのアカウントに追加される通貨の金額
- mac_address:ユーザーのwifi mac_address(オプション)
サーバレスポンス
Tapjoyサーバーは、アプリ開発者のサーバーから200または403レスポンスを受け取ります。
アプリ開発者のサーバーが200をレスポンスする条件:
- ユーザーが通貨を正常に獲得した場合のみ
アプリ開発者のサーバーが403をレスポンスする条件:
- 算出された値とベリファイアが一致しない場合
- システムでsnuidパラメーターが不明である場合
- またはその他のエラーが発生し再試行できない場合
Tapjoyサーバーがその他の応答を受け取った場合、Tapjoyは2分毎に4日間トライし続けます。そして、20秒以内にアプリ開発者サーバからレスポンスがない場合Tapjoyはリクエストを失敗と認識します。 注意:コールバックのレスポンスはUTF-8でエンコードしてください。UTF-8以外のエンコードの場合HTTPStatusCode=200であってもTapjoyは失敗したリクエストと認識する場合があります。
不正アクセス対策
コールバックを登録する際には、[秘密キー](アプリの秘密キーではありません。)を指定します。
仮想通貨の秘密鍵が存在する場合、Tapjoyは次のパラメーターをコールバックします:
- id:特定の仮想通貨付与イベントに割り振られたユニークID (仮想通貨のIDではありません)
- verifier:IDのMD5ハッシュ、snuid、仮想通貨と秘密鍵
下記の場合は不正アクセスになります。
- IDが重複利用されている。
- ベリファイアが一致しない。
- コールバックがTapjoy以外のサーバが届いている。
ベリファイア
ベリファイアはIDのMD5ハッシュ、snuid、仮想通貨と秘密鍵を取得することで計算され、コロンで区切られます。 Rubyコードでは、次のようになります。
Digest::MD5.hexdigest("#{id}:#{snuid}:#{currency}:#{secret_key}")
アプリ開発者のサーバーは、ベリファイアを再計算し、一致しないリクエストを却下します。ベリファイアが一致しない場合、サーバーは403レスポンスを返します。
NO_CALLBACK
アプリの仕様によっては、Tapjoyからのコールバックがない方が望ましい場合があります。この場合、上記のURLの箇所に NO_CALLBACK という文字列を指定すれば、不要なサーバへのアクセスがなくなります。このような状況は、例えばメディエーションを使用していて、メディエーション パートナー側の提供する方法ですべてのリワードを処理するような場合です。この場合、NO_CALLBACK をURLに指定すれば、固定リワードのビデオからリワード量0のコールバックを受け取り続ける事がなくなります。
ユーザーID
ユーザーIDは自社管理通貨を使用する場合には最も重要になる概念です。ユーザIDはユーザーを特定するIDです。アプリがユーザIDを持っていない場合は広告ID(advertising_id)或はMacAddressをセットします。ユーザIDの最大文字数は190文字です。SetUserIDでセットされたユーザIDはコールバックURLのsnuidにセットされます。setUserID はTapjoy connect の成功後できるだけ早くに、広告コンテンツをリクエストするより前に設定される必要があります。 SDK 11.7 以降では setUserID が成功したか否かをコールバックする機能がご利用いただけます。この機能により、広告コンテンツをリクエストする前にsetUserID が成功しているかを確認できるようになります。
GDPR準拠の観点から、UserID として認識可能もしくは特定可能な形の情報(ユーザー名、実名、メールアドレス等)を含むべきではありません。
セキュリティおよび不正防止の観点から、設定するユーザーIDはユーザーのゲーム内での活動全体を通して一意となるようにして下さい(例えば、レベルが上がるたびに別のIDとなるなど)。
- On iOS 6 or above, call setUserID("vendor_id:").
- On iOS 5 or below, call setUserID("mac_address:
- On cellular Android devices, call setUserID("device_id:").
- On wifi-only Android devices (such as a Nexus 7), call setUserID("device_id:".)
iOS手順
[Tapjoy setUserID:@"userID"];
Android手順
Tapjoy.setUserID(String userID);
TROUBLESHOOTING: コールバックURLのsnuidの値がsetUserIDでセットしたユーザIDと異なる場合は、ユーザがTapjoy広告をクリックする前にセットされていないかも知れません。setUserIDはTapjoyコネクトコールの直後に使用され、アプリ起動時に確実に呼び出されるような実装をお勧めします。
user ID を設定していない場合、システムは使用可能な端末IDを使用します。多くの場合は端末の広告IDが指定されますが、SDK のバージョンや端末モデル、OSバージョン、Google Play Services 等の組み合わせによってIDの種類は異なる場合があります。これは、Android ID、Tapjoy 内部ID、mac_address 等が指定される場合があります。
仮想通貨の乗法加算の実装 (非推奨)
常連ユーザーに対して、各広告に対し仮想通貨を乗法加算して、付与額を引き上げることができます。Tapjoyのサーバーからコールバックを受け取った場合はアプリ開発者のサーバー側で通貨の乗法加算の管理をする必要がありますのでご注意ください。 注意:こちらはTapjoyが管理する仮想通貨には使用できません。
iOS手順
// Where mult is the currency multiplier value. + (void)setCurrencyMultiplier:(float)mult;
Android手順
// Where mult is the float currency multiplier value. Tapjoy.setCurrencyMultiplier(float mult)
複数の仮想通貨
アプリで複数の仮想通貨を扱い異なるオファーウォールを表示したい場合は複数の仮想通貨の実装をご参照してください。
仮想通貨のTapjoy管理から自社管理への切り替え
仮想通貨のTapjoy管理を利用するアプリで自社管理へ切り返す場合は以下の作業が必要になります。
- 新規AppIDを作成します。ユーザが既存アプリでTapjoy広告を利用する時の不具合を防げます。
- 既存AppIDで広告出稿をすべて停止します。広告出稿を再開始する場合は新規AppIDで再作成します。
- Tapjoy管理時のgetTapPoints, AwardTapPointsとspendTapPointsを利用しないでください。
- 仮想通貨のTapjoy管理から自社管理へ切り替える場合は事前にTapjoyアカウントマネージャと相談する事をおすすめします。
ユーザの仮想通貨を移動するには、下記手順をおすすめします。
- 既存App IDで起動しgetCurrencyBalanceですべての仮想通貨を取得します。
- 取得した仮想通貨を自社管理サーバに更新します。
- 新規App IDでアプリを再起動します。
仮想通貨の自社管理を検討している方はParseやUrbanAirshipのソリューションがご参考になれます。