JPNTapjoy管理仮想通貨
Tapjoy管理仮想通貨は、Tapjoy のサーバにユーザの仮想通貨の残高を保持するものです。この機能は、Tapjoy SDKを実装するアプリ開発者に対して無償で提供されるサービスです。 この方法を利用する場合、アプリ開発者はユーザーの仮想通貨データを保存するためのシステム構築の作業が必要ありません。実装は比較的簡単で、下記のように行います。
1. 仮想通貨残高の取得
ユーザーの仮想通貨残高を取得するには、下記のメソッドを呼び出します:
仮想通貨のベスト プラクティス: ユーザーの最新の残高を得るために、getCurrencyBalance を多くの箇所で呼ぶようにする事をお勧めします。通常はアプリ起動時、レジューム時、Tapjoyコンテンツが閉じた時にユーザーの残高をチェックします。また、広告コンテンツが閉じた3.5秒後にgetCurrencyBalanceを呼び出す事を特にお勧めします。これにより、広告が終了した後にTapjoyサーバがユーザーの仮想通貨残高を変更する時間的余裕が取れるようになります。コンテンツ表示終了直後にgetCurrencyBalanceを呼ぶと、リワード額の残高への反映が間に合わない場合があります。
注: Tapjoyはユーザーへのリワードを可能な限り素早く付与しますが、ユーザーがすぐにリワードされる事は保証できません。ユーザーへリワードを行う時間に関わる要素が多く割るため、ユーザーへのリワードが行われる時間を決定する事は困難です。ベスト・プラクティスとしては、動画広告が閉じた後に仮想通貨残高をチェックするのに加え、定期的、および起動・レジューム・レベル完了・アプリ内ストアの表示前等のアプリイベントで残高を確認する事をお勧めします。また、ユーザーにオファーの完了までに時間がかかる場合がある旨を知らせておく事もお勧めします。
iOS 手順
// This method requests the tapjoy server for current virtual currency of the user.
//Get currency
[Tapjoy getCurrencyBalanceWithCompletion:^(NSDictionary *parameters, NSError *error) {
if (error) {
//Show error message
NSLog(@"getCurrencyBalance error: %@", [error localizedDescription]);
} else {
//Update currency value of your app
NSLog(@"getCurrencyBalance returned %@: %d", parameters[@"currencyName"], [parameters[@"amount"] intValue]);
}
}];
上記のように、仮想通貨残高はコンプリーションのブロックで通知されます。parametersディクショナリの“currencyName”キーで仮想通貨の名前が、"amount"でユーザーの残高が取得できます。
実証の詳細についてはSDKパッケージに含まれるサンプルアプリを参考にして下さい。
Android 手順
Tapjoy.getCurrencyBalance(new TJGetCurrencyBalanceListener(){
@Override
public void onGetCurrencyBalanceResponse(String currencyName, int balance) {
Log.i(TAG, "getCurrencyBalance returned " + currencyName + ":" + balance);
}
@Override
public void onGetCurrencyBalanceResponseFailure(String error) {
Log.i("Tapjoy", "getCurrencyBalance error: " + error);
}
});
仮想通貨残高は TJGetCurrencyBalanceListener に実装した onGetCurrencyBalanceResponse(String currencyName, int balance) コールバックで currencyName が仮想通貨名、balance が仮想通貨残高となるパラメータで通知されます。エラーについては onGetCurrencyBalanceResponseFailure(String error) コールバックメソッドに通知されます。
注: getCurrencyBalance(…) をアプリの起動時やレジューム時に呼び出す事をお勧めします。仮想通貨のSPENDおよびAWARDを行う場合のコールバックでもユーザーの仮想通貨残高が通知されるので、この値をユーザーの最新の仮想通貨残高として使用して下さい。
Unity 手順
// Get currency
Tapjoy.GetCurrencyBalance();
// on enable, add delegates
void OnEnable() {
Tapjoy.OnGetCurrencyBalanceResponse += HandleGetCurrencyBalanceResponse;
Tapjoy.OnGetCurrencyBalanceResponseFailure += HandleGetCurrencyBalanceResponseFailure;
}
// on disable, remove delegates
void OnDisable() {
Tapjoy.OnGetCurrencyBalanceResponse -= HandleGetCurrencyBalanceResponse;
Tapjoy.OnGetCurrencyBalanceResponseFailure -= HandleGetCurrencyBalanceResponseFailure;
}
public void HandleGetCurrencyBalanceResponse(string currencyName, int balance) {
Debug.Log("C#: HandleGetCurrencyBalanceResponse: currencyName: " + currencyName + ", balance: " + balance);
}
public void HandleGetCurrencyBalanceResponseFailure(string error) {
Debug.Log("C#: HandleGetCurrencyBalanceResponseFailure: " + error);
}
仮想通貨残高はOnGetCurrencyBalanceResponseに指定したハンドラに currencyName と balance パラメータで通知されます。エラーについてはOnGetCurrencyBalanceResponseFailure ハンドラにエラー詳細がerror パラメータとして通知されます。
AIR Instructions
// Get currency
TapjoyAIR.getCurrencyBalance();
// Setup handlers
TapjoyAIR.addEventListener(TJCurrencyEvent.GET_CURRENCY_BALANCE_SUCCESS, tapjoyCurrencyEventHandler);
TapjoyAIR.addEventListener(TJCurrencyEvent.GET_CURRENCY_BALANCE_FAILURE, tapjoyCurrencyEventHandler);
private function tapjoyCurrencyEvents(event:TJCurrencyEvent):void {
trace("Tapjoy sample event listener for " + event.type + ", " + event.balance + ", " + event.currencyName);
}
仮想通貨残高は TJCurrencyEvent.GET_CURRENCY_BALANCE_SUCCESS に指定したハンドラに currencyName と balance プロパティを持つオブジェクトで通知されます。エラーはTJCurrencyEvent.GET_CURRENCY_BALANCE_FAILURE ハンドラで通知されます。
2. ユーザーが仮想通貨を得たかを確認する
iOS 手順
アプリが最後にユーザーの仮想通貨残高を確認してから、ユーザーが仮想通貨を得た場合にユーザーに通知するには、ノーティフィケーション オブザーバを次のように指定します:
// Set the notification observer for earned-currency-notification. It's recommended that this be placed within the applicationDidBecomeActive method.
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(showEarnedCurrencyAlert:) name:TJC_CURRENCY_EARNED_NOTIFICATION object:nil];
// In the following method, you can set a custom message or use the default UIAlert to inform the user that they just earned some currency.
- (void)showEarnedCurrencyAlert:(NSNotification*)notifyObj
{
NSNumber *currencyEarned = notifyObj.object;
int earnedNum = [currencyEarned intValue];
NSLog(@"Currency earned: %d", earnedNum);
// Pops up a UIAlert notifying the user that they have successfully earned some currency.
// This is the default alert, so you may place a custom alert here if you choose to do so.
[Tapjoy showDefaultEarnedCurrencyAlert];
// This is a good place to remove this notification since it is undesirable to have a pop-up alert more than once per app run.
[[NSNotificationCenter defaultCenter] removeObserver:self name:TJC_CURRENCY_EARNED_NOTIFICATION object:nil];
}
Android 手順
アプリが最後にユーザーの仮想通貨残高を確認してから、ユーザーが仮想通貨を得た場合にユーザーに通知するには、CurrencyListenerを次のように指定します:
// Get notifications whenever Tapjoy currency is earned.
Tapjoy.setEarnedCurrencyListener(new TJEarnedCurrencyListener() {
@Override
public void onEarnedCurrency(String currencyName, int amount) {
Log.i("Tapjoy", "You've just earned " + amount + " " + currencyName);
}
});
TJEarnedCurrencyListenerに実装したonEarnedCurrency(String currencyName, int amount)コールバックに通知されるようになります。例えば、ある時点での仮想通貨残高が100で、ユーザーが25仮想通貨のオファーを完了したとします。getCurrencyBalance()メソッドが次に呼ばれると、 onEarnedCurrency メソッドが amount に 25 の値で呼ばれます。
Unity 手順
// on enable, add delegates
void OnEnable() {
Tapjoy.OnEarnedCurrency += HandleEarnedCurrency;
}
// on disable, remove delegates
void OnDisable() {
Tapjoy.OnEarnedCurrency -= HandleEarnedCurrency;
}
public void HandleEarnedCurrency(string currencyName, int amount) {
Debug.Log("C#: HandleEarnedCurrency: currencyName: " + currencyName + ", amount: " + amount);
}
OnEarnedCurrency に指定したハンドラに、currencyName と amount パラメータ で増えた仮想通貨が通知されます。
AIR 手順
TapjoyAIR.addEventListener(TJEarnedCurrencyEvent.EARNED_CURRENCY, tapjoyEarnedCurrencyEventHandler);
private function tapjoyEarnedCurrencyEventHandler(event:TJEarnedCurrencyEvent):void
{
trace("You can notify user's here that they've just earned " + event.amount + " " + event.currencyName);
}
TJEarnedCurrencyEvent.EARNED_CURRENCY に指定したハンドラに、TJEarnedCurrencyEvent オブジェクトで通知されます。そのオブジェクトには currencyName と amount プロパティが指定されています。
3. Tapjoy管理仮想通貨を消費する
ユーザーの仮想通貨を消費するには、次のメソッドを呼び出します:
iOS 手順
// This method call will deduct 10 virtual currencies from the user's total.
[Tapjoy spendCurrency:10 completion:^(NSDictionary *parameters, NSError *error) {
if (error) {
NSLog(@"spendCurrency error: %@", [error localizedDescription]);
} else {
NSLog(@"spendCurrency returned %@: %d", parameters[@"currencyName"], [parameters[@"amount"] intValue])
}
}];
上記にあるように、コンプリーション ブロックで "currencyName" に仮想通貨名、"amout" に残高を含むparameterディクショナリオブジェクトで仮想通貨残高が通知されます。
Android 手順
Tapjoy.spendCurrency(10, new TJSpendCurrencyListener() {
@Override
public void onSpendCurrencyResponse(String currencyName, int balance) {
Log.i("Tapjoy", currencyName + ": " + balance);
}
@Override
public void onSpendCurrencyResponseFailure(String error) {
Log.i("Tapjoy", "spendCurrency error: " + error);
}
});
TJSpendCurrencyListener のonSpendCurrencyResponse(String currencyName, int balance) に実装したメソッドに仮想通貨残高が通知されます。エラーの場合にはonSpendCurrencyResponseFailure(String error)メソッドに通知されます。
Unity 手順
// Spend currency
Tapjoy.SpendCurrency(10);
// on enable, add delegates
void OnEnable() {
Tapjoy.OnSpendCurrencyResponse += HandleSpendCurrencyResponse;
Tapjoy.OnSpendCurrencyResponseFailure += HandleSpendCurrencyResponseFailure;
}
// on disable, remove delegates
void OnDisable() {
Tapjoy.OnSpendCurrencyResponse -= HandleSpendCurrencyResponse;
Tapjoy.OnSpendCurrencyResponseFailure -= HandleSpendCurrencyResponseFailure;
}
public void HandleSpendCurrencyResponse(string currencyName, int balance) {
Debug.Log("C#: HandleSpendCurrencyResponse: currencyName: " + currencyName + ", balance: " + balance);
}
public void HandleSpendCurrencyResponseFailure(string error) {
Debug.Log("C#: HandleSpendCurrencyResponseFailure: " + error);
}
OnSpendCurrencyResponseに指定したハンドラにcurrencyNameおよびbalanceパラメータで仮想通貨残高が通知されます。エラーの場合にはOnSpendCurrencyResponseFailureハンドラに通知されます。
AIR 手順
// Spend currency
TapjoyAIR.spendCurrency(10);
// Setup handlers
TapjoyAIR.addEventListener(TJCurrencyEvent.SPEND_CURRENCY_SUCCESS, tapjoyCurrencyEventHandler);
TapjoyAIR.addEventListener(TJCurrencyEvent.SPEND_CURRENCY_FAILURE, tapjoyCurrencyEventHandler);
private function tapjoyCurrencyEventHandler(event:TJCurrencyEvent):void {
trace("Tapjoy sample event listener for " + event.type + ", " + event.balance + ", " + event.currencyName);
}
TJCurrencyEvent.SPEND_CURRENCY_SUCCESSに指定したハンドラに仮想通貨残高が通知されます。引数のTJCurrencyEventオブジェクトはcurrencyNameおよびbalanceプロパティを含んでいます。エラーの場合にはTJCurrencyEvent.SPEND_CURRENCY_FAILUREハンドラに通知されます。
4. Tapjoy管理仮想通貨を付与する
ご不便をおかけしますが、新規アプリで本機能をご利用になる場合はアカウントマネージャーにご相談の上、許可を得る必要があります。
ユーザーの仮想通貨を増加するには、次のメソッドを呼び出します:
iOS 手順
// This method call will award 10 virtual currencies to the user's total.
[Tapjoy awardCurrency:10 completion:^(NSDictionary *parameters, NSError *error) {
if (error) {
NSLog(@"awardCurrency error: %@", [error localizedDescription]);
} else {
NSLog(@"awardCurrency returned %@: %d", parameters[@"currencyName"], [parameters[@"amount"] intValue])
}
}];
上記にあるように、コンプリーション ブロックで "currencyName" に仮想通貨名、"amout" に残高を含むparameterディクショナリオブジェクトで仮想通貨残高が通知されます。
Android 手順
Tapjoy.awardCurrency(10, new TJAwardCurrencyListener() {
@Override
public void onAwardCurrencyResponseFailure(String error) {
Log.i("Tapjoy", "awardCurrency error: " + error); }
@Override
public void onAwardCurrencyResponse(String currencyName, int balance) {
Log.i("Tapjoy", currencyName + ": " + balance);
}
});
TJAwardCurrencyListener onAwardCurrencyResponse(String currencyName, int balance) に実装したメソッドに仮想通貨残高が通知されます。
Unity 手順
// Award currency
Tapjoy.AwardCurrency(10);
// on enable, add delegates
void OnEnable() {
Tapjoy.OnAwardCurrencyResponse += HandleAwardCurrencyResponse;
Tapjoy.OnAwardCurrencyResponseFailure += HandleAwardCurrencyResponseFailure;
}
// on disable, remove delegates
void OnDisable() {
Tapjoy.OnAwardCurrencyResponse -= HandleAwardCurrencyResponse;
Tapjoy.OnAwardCurrencyResponseFailure -= HandleAwardCurrencyResponseFailure;
}
public void HandleAwardCurrencyResponse(string currencyName, int balance) {
Debug.Log("C#: HandleAwardCurrencySucceeded: currencyName: " + currencyName + ", balance: " + balance);
}
public void HandleAwardCurrencyResponseFailure(string error) {
Debug.Log("C#: HandleAwardCurrencyResponseFailure: " + error);
}
OnAwardCurrencyResponseに指定したハンドラにcurrencyNameおよびbalanceパラメータで仮想通貨残高が通知されます。エラーの場合にはOnAwardCurrencyResponseFailureハンドラに通知されます。
Air 手順
// Award currency
TapjoyAIR.awardCurrency(10);
// Setup handlers
TapjoyAIR.addEventListener(TJCurrencyEvent.AWARD_CURRENCY_SUCCESS, tapjoyCurrencyEventHandler);
TapjoyAIR.addEventListener(TJCurrencyEvent.AWARD_CURRENCY_FAILED, tapjoyCurrencyEventHandler);
private function tapjoyCurrencyEventHandler(event:TJCurrencyEvent):void {
trace("Tapjoy sample event listener for " + event.type + ", " + event.balance + ", " + event.currencyName);
}
TJCurrencyEvent.AWARD_CURRENCY_SUCCESSに指定したハンドラに仮想通貨残高が通知されます。引数のTJCurrencyEventオブジェクトはcurrencyNameおよびbalanceプロパティを含んでいます。エラーの場合にはTJCurrencyEvent.AWARD_CURRENCY_FAILUREハンドラに通知されます。
5. Tapjoy管理仮想通貨をテストする
オファーウォールでテスト広告をみる場合、アプリにテスト端末を追加します。 これによりオファーウォールにテスト広告が表示されるため、仮想通貨を容易にテストできるようになります。
また、Tapjoyダッシュボードの"Get User Balance"ツールを使う事もできます:
アプリがこのツールで表示される値と違う残高を表示している場合、アプリがTapjoyで管理している仮想通貨と同期していない事になります。こうした状況は通常はアプリで getCurrencyBalance を充分な頻度で呼ぶ事で修正できます。
6. ベストプラクティス/追加の情報
- 注意: awardCurrencyとspendCurrencyの呼び出しを確認し、成功した場合のみコンテンツのアンロックや購入を行うようにして下さい。awardCurrencyやspendCurrencyの呼び出しが失敗した場合、端末が不正に操作されている可能性があります。SDKに含まれるTapjoy EasyAppを確認して下さい。
- Tapjoy仮想通貨をクライアントでのノーティフィケーションでのみ使用し、値をアプリ内に保存する実装を行うパブリッシャーもいますが、アプリ内に保存された仮想通貨の値のみに依存して仮想通貨の値を管理する事は避けるべきです。こうした実装を行っていて問題が発生した場合に弊社では対応する事ができなくなります。この状況が問題になる場合には、自社管理仮想通貨の利用を検討して下さい。
- spendCurrency はアイテムやコンテンツをアンロックする場合などにのみ使用するようにして下さい。
- Tapjoy管理仮想通貨はアプリIDにつき一つしか設定できません。複数の仮想通貨を使用する場合は、自社管理仮想通貨を使用して下さい。
- 仮想通貨残高はアプリ毎、端末毎に保持されます。端末を跨いだ残高の共用はできません。
注意: Tapjoyはユーザーへのリワードを可能な限り素早く付与しますが、ユーザーがすぐにリワードされる事は保証できません。ユーザーへリワードを行う時間に関わる要素が多く割るため、ユーザーへのリワードが行われる時間を決定する事は困難です。ベスト・プラクティスとしては、動画広告が閉じた後に仮想通貨残高をチェックするのに加え、定期的、および起動・レジューム・レベル完了・アプリ内ストアの表示前等のアプリイベントで残高を確認する事をお勧めします。また、ユーザーにオファーの完了までに時間がかかる場合がある旨を知らせておく事もお勧めします。