자체관리 가상화폐

자체 관리 가상화폐는 자체 서버로 사용자의 가상화폐를 처리 할 때 사용됩니다. 이 방법을 사용하면 사용자의 가상화폐를 더 세부적으로 제어 할 수 있지만 모든 사용자의 가상화폐 금액을 저장하고 처리하는 백엔드 작업을 전적으로 책임져야합니다. getCurrencyBalance, awardCurrency 또는 spendCurrency는 관리 가상화폐에서만 사용할 수 있습니다. Tapjoy는 자체 관리 가상화폐에 대해 클라이언트 측/앱 측 알림을 제공하지 않습니다. 귀하는 콜백 서버를 호출 할 때 앱과 사용자에게 알릴 책임이 있습니다. 자체 관리 가상화폐를 사용하려면 콜백 서버를 설정해야합니다.

참고 : Tapjoy는 가능한 한 빨리 사용자에게 보상하기 위해 최선을 다하고 있지만 사용자가 즉시 보상을받을 것이라고 보장 할 수는 없습니다. 사용자에게 보상하는 데 걸리는 시간을 결정하는 많은 요소가 있습니다. 모범 사례로서 정기적으로 업데이트 된 잔액을 확인하고 앱 시작, 앱 재개, 레벨 간, 동영상 광고 종료 등과 같은 특정 앱 이벤트 후, 스토어로드 전 등을 확인해야합니다. 또한 사용자가 제안이 완료되기까지 시간이 걸릴 수 있음을 알고 있습니다.

참고 : 각 플랫폼에는 자체 관리되는 경우에도 자체 가상화폐가 있어야합니다.

1. 콜백 URL

사용자가 광고를 완료하여 가상화폐를 획득할 조건이 충족되면 탭조이 서버가 가상화폐 생성 시 설정된 콜백 URL을 HTTP GET 방식으로 요청합니다. 이때 전달되는 파라미터의 형식은 다음과 같습니다.

<callback_url>?snuid=<user_id>&currency=<currency>&mac_address=<mac_address>

//Example

http://www.sampledoman.com/payments/offers/tapjoy?snuid=42&currency=50&mac\_address=00-16-41-34-2C-A6

기본 요청 파라미터에는 보상 트랜잭션에 대한 아이디 id, 퍼블리셔 사용자 아이디 snuid, 가상화폐양 currency 그리고 가능한 경우 사용자의 wi-fi mac_address 가 포함됩니다.

Server 응답

Tapjoy 서버는 서버로부터 200(성공) 또는 403(실패) 응답을 기대합니다.

서버는 다음과 같은 경우에만 200으로 응답해야합니다.

• 사용자가 성공적으로 가상화폐를 받았습니다.

서버는 다음과 같은 경우 403으로 응답해야합니다.

• verifier 파라미터가 계산된 값과 일치하지 않는 경우.
• 시스템에서 snuid 파라미터를 알 수 없는 경우.
• 재시도해서는 안되는 다른 오류가있는 경우.

Tapjoy 서버가 200 또는 403 이외의 응답을 받으면 Tapjoy는 콜백 요청을 재시도합니다. (Tapjoy가 콜백을 계속 재시도하므로 200이 아닌 응답을 제공하는 경우 실제로 사용자에게 보상하지 않는 것이 매우 중요합니다. 그렇지 않으면 중복 보상이 이루어질 수 있습니다.) 재시도는 4일 동안 2분마다 이루어지며, 서버가 응답하는데 5초 이상 걸리는 경우도 요청이 실패한 것으로 처리합니다.

참고 : 콜백 URL 응답의 응답 본문은 UTF-8이어야합니다. UTF-8이 아닌 경우 200을 반환하더라도 재시도합니다.

부정 방지/예방을 위한 파라미터

대시보드 > 모네타이즈 > 가상화폐 > 생성/수정 화면에서 가상화폐 비밀키를 확인할 수 있습니다. 이 키는 애플리케이션 SDK키와는 다릅니다. 이 가상화폐 비밀키를 사용하여 콜백요청을 검증할 수 있습니다.

가상화폐에 비밀키가 있는 경우(secret_key =) Tapjoy 서버는 콜백 요청에 다음 파라미터를 추가합니다.

-id : 가상화폐 콜백 요청 트랜젝션에 대한 아이디입니다. (이것은 가상화폐 _id가 아니라 요청 트랜젝션에 대한 _id를 나타냅니다.) -verifier : id, snuid, 가상화폐 및 비밀키 값에 대한 MD5 해시 (아래 참조)

예상되는 부정 접근 시나리오

-재사용 되는 ID 또는 잘못된 verifier 값인 경우, 콜백 URL은 Tapjoy에서 온 것이 아니므로 부정 접근으로 간주해야합니다. -사용자 ID에 정수만 포함되어있는 경우 간단한 유효성 검사를 수행하여 사용자 ID가 조작되고 있지 않은지 확인하는 것이 좋습니다. 예를 들어 Tapjoy는 "001234"와 "1234"에 대해 두개의 별도 사용자 ID로 처리하지만 자체 백엔드 서버 로직은 그렇지 않을 수 있습니다.

Verifier

verifier는 콜론으로 구분 된 id, snuid, 가상화폐 및 비밀키의 MD5 해시를 사용하여 계산됩니다. Ruby 코드에서는 다음과 같습니다.

Digest::MD5.hexdigest("#{id}:#{snuid}:#{currency}:#{secret_key}")

서버는 verifier를 다시 계산하고 일치하지 않는 요청을 거부해야합니다. verifier가 일치하지 않는 경우 403 Forbidden으로 응답해야합니다.

각 애플리케이션에는 별도의 비밀키가 있어야합니다. 모든 애플리케이션에 동일한 비밀키를 사용하지 마십시오. 이 경우 한 애플리케이션에서 사용자에게 보상을 제공하면 다른 애플리케이션의 사용자에게도 보상이 제공 될 수 있습니다. 또한 위의 id는 currency _id가 아닌 request _id를 나타냅니다.

2. 사용자 ID

자체 관리 가상화폐를 사용하는 경우 사용자 ID를 설정하는 것이 매우 중요합니다. 이 값은 콜백 URL에서 snuid로 설정되는 값입니다. 콘텐츠가 요청되기 전에 연결 플래그를 사용하여 connect 요청 시 사용자 ID를 설정하는 것이 좋습니다.

잘못 설정하면 사용자에게 보상이 제공되지 않으며 수익도 지급되지 않습니다. 사용자 ID는 고유한 사용자 ID(일반적으로 숫자)로 설정해야 합니다.

데이터 보안 및 GDPR 준수를 위해 setUserID 매개변수에는 사용자 이름, 실명 또는 이메일 주소와 같은 인식 가능하거나 식별 가능한 정보가 포함되어서는 안됩니다. 보안 및 사기 탐지를 위해 사용자 ID는 앱에서 사용자의 라이프사이클 동안 일정해야 합니다. (예를 들어, 사용자 ID 매개변수를 사용하여 사용자의 레벨이나 점수와 같은 정보를 전달하지 마십시오.)

The User ID can be up to 190 characters long.

아래 코드 샘플은 연결 플래그를 사용하는 방법과 필요한 경우 'setUserID' API를 직접(연결 후) 호출하는 방법을 보여줍니다. API를 호출할 때 콜백을 직접 사용하여 ID가 성공적으로 설정되었는지 확인하십시오. 가능한 경우 연결 플래그를 사용하는 것이 좋습니다.

iOS

// Recommended approach using connect flag
NSDictionary *connectFlags = @{TJC_OPTION_USER_ID : @"<USER_ID_HERE>"};
[Tapjoy connect:@"SDK_KEY_GOES_HERE" options:connectFlags];

// Setting the user id directly
[Tapjoy setUserIDWithCompletion:@"<USER_ID_HERE>" completion:^(BOOL success, NSError *error) {

}];

Android

// Recommended approach using connect flag
Hashtable<String, Object> connectFlags = new Hashtable<String, Object>();
connectFlags.put(TapjoyConnectFlag.USER_ID, "<USER_ID_HERE>"); // Important for self-managed currency

Tapjoy.connect(getApplicationContext(), "SDK_KEY_GOES_HERE", connectFlags, new TJConnectListener() {...});

// Setting the user id directly

Tapjoy.setUserID("<USER_ID_HERE>", new TJSetUserIDListener() {
  @Override
  public void onSetUserIDSuccess() {
    
  }

  @Override
  public void onSetUserIDFailure(String error) {

  }
});

Unity Instructions

// Recommended approach using connect flag
Dictionary<string,string> connectFlags = new Dictionary<string,string>();
connectFlags.Add("TJC_OPTION_USER_ID", "<USER_ID_HERE>");

#if UNITY_ANDROID
  Tapjoy.Connect("your_android_sdk_key", connectFlags);
#elif UNITY_IOS
  Tapjoy.Connect("your_ios_sdk_key", connectFlags);
#endif

// Callbacks for SetUserID
TJPlacement.OnSetUserIDSuccess += HandleOnSetUserIDSuccess;
TJPlacement.OnSetUserIDFailure += HandleOnSetUserIDFailure;

// Setting the user id directly
Tapjoy.SetUserID("<USER_ID_HERE>")

자세한 내용은 iOS, Android 및 Unity 문서를 확인하세요.

문제 해결 : setUserID를 호출하고 콜백 URL의 snuid가 예상한 값이 아닌 경우 사용자가 인앱 오퍼월 또는 tapjoy.com으로 이동하여 광고를 완료하기 전에 setUserID를 호출해야합니다. Tapjoy는 장치와 관련된 사용자 ID가없는 경우 콜백 URL에 장치 ID를 snuid로 보냅니다. 예를 들어 사용자가 앱을 실행한 다음 앱에서 사용자 ID를 보내기 전에 tapjoy.com으로 이동할 수 있습니다. 이를 방지하려면 connect 호출 후 setUserID가 정상적으로 호출되는지 확인해야합니다.

사용자 ID를 설정하지 않은 경우 시스템은 사용 가능한 최적의 장치 ID를 사용하려고 시도합니다. 대부분의 경우 이것은 장치의 광고 ID입니다. 단, SDK 버전, 기기 모델 버전, 기기 OS 버전, Google Play 서비스에 따라 정확한 ID가 다를 수 있습니다. 다른 가능한 값에는 Android ID, udid 및 mac_address가 있습니다.

3. NO_CALLBACK 설정

콜백이 사용하지 않는 시나리오가 있을 수 있습니다. 이 경우 URL에 'NO_CALLBACK'을 입력하면 서버에 대한 불필요한 호출을 피할 수 있습니다. 만일 잘못된 URL을 세팅할 경우 지속적으로 재시도가 발생하여 양사 서버에 부담을 줄 수 있으니 유의해야 합니다.

4. 가상화폐 잔고 설정

매 플레이스먼트 요청시 Tapjoy에 현재 사용자의 가상화폐 잔고를 설정할 수 있습니다. 본 API는 플레이스먼트 요청 전 설정합니다.

iOS

TJPlacement *placement = [TJPlacement placementWithName:@"placementName" delegate:nil];
[placement setBalance:100 forCurrencyId:@"1234" withCompletion:^(NSError * _Nullable error) {
    if (error != nil) {
        //Failure
        NSString *message = error.localizedDescription;
    } else {
        //Success
    }
}]; 

Android

TJPlacement placement = Tapjoy.getPlacement("placement", this);
placement.setCurrencyBalance("1234", 100, new TJSetCurrencyBalanceListener() {
    @Override
    public void onSetCurrencyBalanceSuccess() {
        
    }

    @Override
    public void onSetCurrencyBalanceFailure(int code, String error) {

    }
}); 

Unity

TJPlacement placement = TJPlacement.CreatePlacement("placementName");
placement.SetCurrencyBalance("[CURRENCY_ID]", 100);

// Optional callbacks

void OnEnable() 
{	
    TJPlacement.OnSetCurrencyBalanceSuccess += HandleSetCurrencyBalanceSuccess;	
    TJPlacement.OnSetCurrencyBalanceFailure += HandleSetCurrencyBalanceFailure;	
}

void OnDisable() 
{	
    TJPlacement.OnSetCurrencyBalanceSuccess -= HandleSetCurrencyBalanceSuccess;	
    TJPlacement.OnSetCurrencyBalanceFailure -= HandleSetCurrencyBalanceFailure;
}

public void HandleSetCurrencyBalanceSuccess(TJPlacement placement) 
{

}

public void HandleSetCurrencyBalanceFailure(TJPlacement placement, int code, string error)
{

}

React Native

let placement = new TJPlacement('placementName');
try {
  await placement?.setCurrencyBalance('1234', 100);
} catch (e: any) {
  let code = e.code;
  let message = e.message;
}

필요 잔고

만약 가상화폐 잔고를 설정하였다면 플레이스먼트에 대한 필요 잔고를 설정할 수 있습니다.

iOS

TJPlacement* placement = [TJPlacement placementWithName:@"placementName" delegate:nil];
placement setRequiredAmount:100 forCurrencyId:@"1234" withCompletion:^(NSError * _Nullable error) {
    if (error != nil) {
        //Failure
        NSString *message = error.localizedDescription;
    } else {
        //Success
    }
} 

Android

TJPlacement placement = Tapjoy.getPlacement("placement", this);
placement.setCurrencyAmountRequired("1234", 100, new TJSetCurrencyAmountRequiredListener() {
    @Override
    public void onSetCurrencyAmountRequiredSuccess() {
        
    }

    @Override
    public void onSetCurrencyAmountRequiredFailure(int code, String error) {

    }
}); 

Unity

TJPlacement placement = TJPlacement.CreatePlacement("placementName");
placement.SetRequiredAmount("[CURRENCY_ID]", 200); 

// Optional callbacks

void OnEnable() 
{	
    TJPlacement.OnSetCurrencyAmountRequiredSuccess += HandleSetRequiredAmountSuccess;	
    TJPlacement.OnSetCurrencyAmountRequiredFailure += HandleSetRequiredAmountFailure;}

void OnDisable() 
{	
    TJPlacement.OnSetCurrencyAmountRequiredSuccess -= HandleSetRequiredAmountSuccess;	
    TJPlacement.OnSetCurrencyAmountRequiredFailure -= HandleSetRequiredAmountFailure;
}

public void HandleSetCurrencyBalanceSuccess(TJPlacement placement)
{

}

public void HandleSetCurrencyBalanceFailure(TJPlacement placement, int code, string error)
{

}

public void HandleSetRequiredAmountSuccess(TJPlacement placement)
{

}
public void HandleSetRequiredAmountFailure(TJPlacement placement, int code, string error)
{

} 

React Native

let placement = new TJPlacement('placementName');
try {
await offerwallPlacement?.setRequiredAmount(100, '100');
} catch (e: any) {
  let code = e.code;
  let message = e.message;
} 

5. 리워드 콜백 IP 화이트리스트

리워드 서버에 접속하기 위해 인증(화이트리스트) 설정이 필요할 경우 아래의 Tapjoy IP 를 등록합니다. (업데이트 일자: 2024년 5월 12일)

18.215.207.89
18.235.142.165
23.20.255.113
23.23.134.165
3.210.188.32
3.215.42.140
3.217.209.177
3.218.95.35
3.219.236.53
3.231.137.161

6. Tapjoy 관리에서 자체 관리로 전환

아직 앱을 런칭하지 않았다면 탭조이 대시보드의 가상 화폐 편집 화면에서 탭조이 관리 화폐를 자체 관리 화폐로 전환할 수 있습니다. 콜백 URL 필드에 올바른 형식의 URL(또는 "NO_CALLBACK")을 입력해야 합니다. 그렇지 않으면 변경이 실제로 발생하지 않습니다.

Tapjoy에서 관리하는 가상화폐가 있는 라이브 애플리케이션이 있는 경우 전환 프로세스가 더 복잡합니다. 고려해야 할 몇 가지 사항은 다음과 같습니다.

• 신규 버전을 위해 대시보드에서 새 앱을 생성하고 새로운 SDK키를 사용해야 합니다. 이렇게 하면 최신 버전으로 업그레이드하지 않은 이전 버전의 앱을 사용하는 사용자는 영향을 받지 않습니다. 앱의 자체 관리 가상화폐 버전에 동일한 SDK키를 사용하는 경우 Tapjoy 관리 가상화폐 버전의 모든 사용자는 광고 완료에 대한 보상을 받지 못합니다.
• 이전 앱 ID를 사용하는 모든 광고 캠페인을 비활성화하고 새로운 앱 ID를 사용하도록 모든 광고 캠페인을 다시 만들어야합니다.
• 자체 관리로 전환하려면 앱에서 코드를 변경해야합니다. getCurrencyBalance, awardCurrency 또는 spendCurrency는 Tapjoy 관리 가상화폐에서만 사용할 수 있으므로 해당 기능들을 자체적으로 추가해야 합니다.
• 변경을 고려하기 전에 Tapjoy의 어카운트 메니저에게 문의하는 것이 좋습니다.
• 자체 관리 가상화폐에서 Tapjoy 관리 가상화폐로 전환 할 수 없습니다. 따라서 변경하기 전에 변경을 실행할지 신중히 확인하십시오.

사용자 잔액을 이전하려면 다음 단계를 따르는 것이 좋습니다.

1. 처음 시작할 때 이전 SDK키 (Tapjoy 관리 가상화폐 포함)를 사용하여 getCurrencyBalance를 호출한 후 잔액을 확인합니다.
2. getCurrencyBalance에서 반환한 값으로 잔액을 업데이트합니다.
3. 이후의 모든 시작에서 새 SDK 키를 사용합니다.

자체 관리로 전환을 고려하고 있지만 자체 가상 화폐 서버를 구현하는 방법을 잘 모르겠다면 Parse 또는 UrbanAirship 와 같은 서비스를 검토하실 수 있습니다.