Tapjoy관리 가상화폐

탭조이 관리 가상화폐 (Tapjoy Managed Currency) 옵션을 선택하시면, 어플리케이션 내 사용되는 가상화폐 금액을 탭조이 서버에 저장하실 수 있습니다. 이 서비스는 탭조이SDK를 설치하는 모든 개발사들에게 무료로 제공됩니다. 이 옵션을 선택하실 경우, 어플리케이션 사용자들의 가상화폐 관련 데이터를 저장하는데에 필요한 백앤드 작업 없이, 가상화폐 사용이 가능하게 됩니다.

1. 가상화폐 잔액 불러오기

사용자의 현재 가상화폐를 얻으려면 다음 메소드를 호출하십시오.

구현 권장사항: getCurrencyBalance를 최대한 자주 호출하여 사용자의 잔액이 항상 최신 상태로 유지되도록 하는 것이 좋습니다. 사용자의 잔액을 확인하는 일반적인 시점 앱이 시작될 때, 앱이 다시 시작될 때, Tapjoy 콘텐츠가 닫힐 때, 플레이스먼트 콘텐츠가 사라질 때입니다. 광고 콘텐츠가 사라진 후 3.5 초 후에 getCurrencyBalance(사용중인 플랫폼에 따라 대응하는 API)를 호출하는 것이 특히 유용합니다. 이를 통해 가상화폐 잔액을 확인할 때까지 시스템이 보상 프로세스를 완료할 수 있는 시간을 제공합니다. 콘텐츠 표시가 완료된 직후 getCurrencyBalance를 확인하면 잔액을 쿼리하기 전에 보상이 사용자의 잔액에 반영될 시간이 부족할 수 있습니다.

참고 : Tapjoy는 가능한 한 신속하게 사용자에게 보상을 지급하기 위해 최선을 다하지만, 사용자가 즉시 보상을 받는 것을 보장 할 수는 없습니다. 사용자에게 보상을 지급하는데 걸리는 시간을 결정하는 많은 요소가 있습니다. 가장 좋은 방법은 동영상 광고가 닫히는 시점에 잔액을 확인하는 것 외에도 정기적으로 확인하거나 앱 시작, 앱 재개와 같은 특정 앱 이벤트 후, 레벨 사이, 상점 로드 전 등의 시점에 업데이트된 잔액을 확인하는 것입니다. 또한 보상지급이 완료되기까지 시간이 걸릴 수 있음을 사용자에게 알려주는 것도 권장하는 방법입니다.

iOS 연동

// 이 메소드가 Tapjoy 서버에 가상화폐 잔액정보를 요청합니다.
// 가상화폐 가져오기
[Tapjoy getCurrencyBalanceWithCompletion:^(NSDictionary *parameters, NSError *error) {
	if (error) {
		//에러 처리
		NSLog(@"getCurrencyBalance error: %@", [error localizedDescription]);
	} else {
		//가상화폐 잔액 표시
		NSLog(@"getCurrencyBalance returned %@: %d", parameters[@"currencyName"], [parameters[@"amount"] intValue]);
	}
}];

위 코드에서 설명하는 바와 같이 완료 블록에서 가상화폐 잔액에 대한 정보를 얻을 수 있습니다. 파라미터 "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) 콜백 메서드를 통해 가상화폐 잔액을 얻을 수 있습니다. 오류가 발생할 경우 onGetCurrencyBalanceResponseFailure(String error) 콜백 메서드에서 오류 대한 정보를 받습니다.

참고: 응용 프로그램을 시작하고 다시 시작할 때 getCurrencyBalance()를 호출하는 것이 가장 좋습니다. SPEND 및 AWARD 에 대한 콜백 호출은 사용자의 총 가상화폐 잔액도 반환하므로 이를 사용하여 사용자가 보유한 총 화폐 금액을 업데이트 할 수도 있습니다.

Unity

// 가상화폐 가져오기
Tapjoy.GetCurrencyBalance();

// 델리게이트 추가
void OnEnable() {
	Tapjoy.OnGetCurrencyBalanceResponse += HandleGetCurrencyBalanceResponse;
	Tapjoy.OnGetCurrencyBalanceResponseFailure += HandleGetCurrencyBalanceResponseFailure;
}

// 델리게이트 제거
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 및 잔액 파라미터가 전달됩니다. OnGetCurrencyBalanceResponseFailure 헨들러에서 오류에 대한 알림을 받습니다.

AIR

// 가상화폐 가져오기
TapjoyAIR.getCurrencyBalance();

// 헨들러 셋업
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 이벤트 핸들러에서 화폐 잔액에 대한 이벤트을 받게되며, TJCurrencyEvent 이벤트가 전달됩니다. 이 이벤트는 currencyName 및 가상화폐 잔액을 포함합니다. TJCurrencyEvent.GET_CURRENCY_BALANCE_FAILURE 이벤트 핸들러에서 오류에 대한 이벤트를 받습니다.

2. 사용자 화폐 획득여부 확인

사용자 화폐 획득에 대한 리스너의 실행은 능동적으로 실행되는 것이 아니라, getCurrencyBalance API를 호출했을때 이전 잔액과 차이가 존재하면 호출됩니다.

iOS

사용자에게 마지막으로 앱이 사용자의 화폐 잔액을 쿼리한 이후 가상화폐를 획득했음을 알리려면 알림에 대한 옵저버를 설정합니다.

// 알림 옵져버 세팅. applicationDidBecomeActive 메서드에 추가하는 것이 좋습니다.
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(showEarnedCurrencyAlert:) name:TJC_CURRENCY_EARNED_NOTIFICATION object:nil];

// 다음 메서드에서 사용자 지정 메시지를 설정하거나 기본 UIAlert를 사용하여 사용자에게 방금 보상을 지급 받았다는 것을 알릴 수 있습니다.
- (void)showEarnedCurrencyAlert:(NSNotification*)notifyObj
{
	NSNumber *currencyEarned = notifyObj.object;
	int earnedNum = [currencyEarned intValue];

	NSLog(@"Currency earned: %d", earnedNum);

    // 사용자에게 보상을 성공적으로 획득했음을 알리는 UIAlert를 표시합니다.
	// 예제는 기본 UI를 사용하므로, 필요한 경우 적절한 커스텀 형식의 UI를 추가할 수 있습니다.
	[Tapjoy showDefaultEarnedCurrencyAlert];

	// 앱이 실행될 때마다 팝업 경고가 두 번 이상 표시되는 것은 바람직하지 않으므로 이 알림을 제거하는 것이 좋습니다.
	[[NSNotificationCenter defaultCenter] removeObserver:self name:TJC_CURRENCY_EARNED_NOTIFICATION object:nil];
}

Android

사용자가 가상화폐를 획득할 때마다 알림을 받게하려면 다음 방법으로 가상화폐 획득 정보를 처리할 리스너를 설정하십시오.

// 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 메서드가 25의 금액으로 실행됩니다.

Unity

// 활성화시 델리게이트 추가
void OnEnable() {
	Tapjoy.OnEarnedCurrency += HandleEarnedCurrency;
}

// 비활성화시 델리게이트 제거
void OnDisable() {
	Tapjoy.OnEarnedCurrency -= HandleEarnedCurrency;
}

public void HandleEarnedCurrency(string currencyName, int amount) {
	Debug.Log("C#: HandleEarnedCurrency: currencyName: " + currencyName + ", amount: " + amount);
}

지정한 OnEarnedCurrency 핸들러에서 획득 한 화폐로 알림을 받게되며 이는 currencyName 및 획득 금액 파라미터를 전달합니다.

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"은 화폐 이름을 제공하고 "amount"는 사용자의 잔액을 제공합니다.

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

// 가상화폐 사용
Tapjoy.SpendCurrency(10);

// 활성화시 델리게이트 추가
void OnEnable() {
	Tapjoy.OnSpendCurrencyResponse += HandleSpendCurrencyResponse;
	Tapjoy.OnSpendCurrencyResponseFailure += HandleSpendCurrencyResponseFailure;
}

// 비활성화시 델리게이트 제거
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 및 잔액 파라미터를 전달합니다. OnSpendCurrencyResponseFailure 핸들러의 오류에 대한 알림을받습니다.

AIR

// 가상화폐 사용
TapjoyAIR.spendCurrency(10);

// 핸들러 설정 
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 및 균형 속성을 포함합니다. TJCurrencyEvent.SPEND_CURRENCY_FAILURE 핸들러에서 오류에 대한 알림을받습니다.

4. Tapjoy 관리 화폐 지급

신규로 연동 중인 앱에서 본 기능을 사용하실 경우 어카운트 매니저의 확인 및 승인이 필요합니다.

사용자에게 일정 금액의 가상화폐를 지급하려면 다음 메소드를 호출하십시오.

iOS

//이 메서드 호출은 사용자의 보유액에서 10개의 가상 화폐를 제공합니다.
[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"은 화폐 이름을 제공하고 "amount"는 사용자의 잔액을 제공합니다.

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

// 가상화폐 지급
Tapjoy.AwardCurrency(10);

// 활성화시 델리게이트 추가
void OnEnable() {
	Tapjoy.OnAwardCurrencyResponse += HandleAwardCurrencyResponse;
	Tapjoy.OnAwardCurrencyResponseFailure += HandleAwardCurrencyResponseFailure;
}

// 비활성화시 델리게이트 제거
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 및 잔액 파라미터를 전달합니다. OnAwardCurrencyResponseFailure 핸들러의 오류에 대한 알림을받습니다.

Air

// 가상화폐 지급
TapjoyAIR.awardCurrency(10);

// 핸들러 설정 
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 및 균형 속성을 포함합니다. TJCurrencyEvent.AWARD_CURRENCY_FAILURE 핸들러의 오류에 대한 알림을받습니다.

5. 테스트

오퍼월에서 테스트 오퍼를 보려면 대시보드 앱설정에서 앱을 위한 테스트 디바이스를 추가 할 수 있습니다. 이렇게하면 오퍼월 상단에 테스트 오퍼가 표시되어 광고 소비 및 보상 프로세스를 쉽게 테스트 할 수 있습니다.

Tapjoy관리 가상화폐 구현이 올바르게 작동하는지 확인하는데 사용할 수 있는 또 다른 도구는 Tapjoy 대시 보드의 "Get User Balance"도구입니다.

앱에서이 도구가 보여주는 것과 다른 잔액을 표시하는 경우 앱이 Tapjoy 잔액과 동기화되지 않았을 가능성이 있습니다. 일반적으로 앱에서 getCurrencyBalance를 충분히 자주 호출하면이 문제를 해결할 수 있습니다.

6. 권장사항 및 추가정보

-중요 : awardCurrency 및 spendCurrency 호출을 확인하고 호출이 성공한 경우에만 콘텐츠/구매 잠금을 해제하십시오. awardCurrency 및 spendCurrency 호출이 실패하면 기기의 잔액이 손상되었을 가능성이 높습니다. 예제는 SDK에 포함 된 Tapjoy EasyApp 프로젝트를 확인하십시오. -일부 퍼블리셔는 클라이언트 측 알림에 대해서만 관리 화폐를 구현하고 화폐를 로컬에 저장합니다. 로컬 디바이스에 저장된 화폐 잔액에 의존하지 않는 것이 좋습니다. 해당 케이스의 문제가 발생하면 지원해 드릴 수 있는 방법이 없습니다. 문제가 발생할 경우 자체 관리 화폐 사용을 고려해야 할 수도 있습니다. -아이템이나 콘텐츠의 잠금 해제를 위해 가상화폐를 사용하는 경우 awardCurrency를 이용하세요. -Tapjoy관리 가상화폐는 앱ID 당 1개의 화폐만 지원합니다. 여러 화폐가 필요한 경우 자체관리 가상화폐를 사용해야합니다. -잔액은 앱별/기기별로 저장되므로 디바이스 간에 잔액을 공유할 수 없습니다.

참고 : Tapjoy는 가능한 한 빨리 사용자에게 보상하기 위해 최선을 다하고 있지만 사용자가 즉시 보상받는 것을 완전히 보장할 수는 없습니다. 사용자에게 보상하는데 걸리는 시간을 결정하는 많은 요소가 있습니다. 가장 좋은 방법은 동영상 광고가 닫히는 시기를 확인하는 것 외에도 정기적으로 그리고 앱 시작, 앱 재개와 같은 특정 앱 이벤트 후, 레벨 증감 사이, 스토어 로드 전 등의 최대한 다양한 시점에 업데이트된 잔액을 확인하는 것입니다. 또한 권장 사항 오퍼가 완료되기까지 시간이 걸릴 수 있음을 사용자에게 알립니다.