このガイドでは、API を統合して、対象となるアプリとリージョンで外部オファーをサポートする方法について説明します。資格要件や地理的範囲など、外部オファー プログラムの詳細については、プログラムの要件をご覧ください。
Play Billing Library のセットアップ
外部オファーの API を使用するには、Android アプリに Play Billing Library の依存関係のバージョン 6.2.1 以降を追加します。以前のバージョンから移行する必要がある場合は、外部オファーを実装する前に移行ガイドの手順に沿って対応してください。
Google Play に接続する
統合プロセスの最初のステップは、課金の統合ガイドで説明されている手順と同じですが、BillingClient
の初期化時にいくつかの違いがあります。
- 外部クーポンを使用することを示す新しいメソッド
enableExternalOffer
を呼び出す必要があります。
次の例は、これらの変更を行った BillingClient
の初期化方法を示しています。
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build();
BillingClient
を初期化したら、統合ガイドの説明のとおりに Google Play への接続を確立する必要があります。
使用できるか確認する
アプリは isExternalOfferAvailableAsync
を呼び出して、外部特典が利用可能であることを確認する必要があります。
外部オファーが利用可能な場合、この API は BillingResponseCode.OK
を返します。アプリが他のレスポンス コードに応答する方法については、レスポンス処理をご覧ください。
Kotlin
billingClient.isExternalOfferAvailableAsync(
object : ExternalOfferAvailabilityListener {
override fun onExternalOfferAvailabilityResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers unavailable, etc.
return
}
// External offers are available. Continue with steps in the
// guide.
})
Java
billingClient.isExternalOfferAvailableAsync(
new ExternalOfferAvailabilityListener() {
@Override
public void onExternalOfferAvailabilityResponse(
BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers being unavailable, etc.
return;
}
// External offers are available. Continue with steps in the
// guide.
}
});
外部取引トークンを準備する
外部取引を Google Play に報告するには、Play Billing Library から生成された外部取引トークンが必要です。ユーザーが外部オファー API を介して外部ウェブサイトにアクセスするたびに、新しい外部取引トークンを生成する必要があります。これを行うには、createExternalOfferReportingDetailsAsync
API を呼び出します。このトークンは、ユーザーがアプリの外に誘導される直前に生成する必要があります。このトークンはキャッシュに保存しないでください。ユーザーがアプリの外に誘導されるたびに新しいトークンを生成する必要があります。
Kotlin
billingClient.createExternalOfferReportingDetailsAsync(
object : ExternalOfferReportingDetailsListener {
override fun onExternalOfferReportingDetailsResponse(
billingResult: BillingResult,
externalOfferReportingDetails: ExternalOfferReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
externalOfferReportingDetails?.externalTransactionToken
// Persist the transaction token locally. Pass it to the external
// website when showExternalOfferInformationDialog is called.
}
})
Java
billingClient.createExternalOfferReportingDetailsAsync(
new ExternalOfferReportingDetailsListener() {
@Override
public void onExternalOfferReportingDetailsResponse(
BillingResult billingResult,
@Nullable ExternalOfferReportingDetails
externalOfferReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
externalOfferReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to the
// external website when showExternalOfferInformationDialog is
// called.
}
});
ユーザー向け情報ダイアログ
外部オファーと統合するには、対象アプリで情報画面を表示して、アプリから外部ウェブサイトに誘導されることをユーザーが把握できるようにする必要があります。情報画面は、外部オファーにリンクする前に、毎回 showExternalOfferInformationDialog
API を呼び出してユーザーに表示する必要があります。
Kotlin
// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;
val listener : ExternalOfferInformationDialogListener =
ExternalOfferInformationDialogListener {
override fun onExternalOfferInformationDialogResponse(
billingResult: BillingResult){
// Check billingResult
}
}
val billingResult = billingClient.showExternalOfferInformationDialog(
activity, listener)
Java
// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;
ExternalOfferInformationDialogListener listener =
new ExternalOfferInformationDialogListener() {
@Override
public void onExternalOfferInformationDialogResponse(
BillingResult billingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
}
// Open the external website, passing along the external transaction
// token as a URL parameter. If the user purchases an item, be sure
// to report the transaction to Google Play.
}
}
BillingResult billingResult =
billingClient.showExternalOfferInformationDialog(activity, listener);
このメソッドが BillingResponseCode.OK
を返した場合、アプリはユーザーを外部ウェブサイトに誘導できます。このメソッドが BillingResponseCode.USER_CANCELED
を返した場合、アプリはウェブサイトを続けて開けません。
Google Play に取引を報告する
外部取引はすべて、バックエンドから Google Play Developer API を呼び出して Google Play に報告する必要があります。createExternalOfferReportingDetailsAsync
API を使用して取得した externalTransactionToken
を提供しながら、外部トランザクションを報告する必要があります。ユーザーが複数の購入を行った場合は、同じ externalTransactionToken
を使用して購入ごとに報告できます。取引を報告する方法については、バックエンド統合ガイドをご覧ください。
レスポンス処理
エラーが発生した場合、メソッド isExternalOfferAvailableAsync
、createExternalOfferReportingDetailsAsync
、showExternalOfferInformationDialog
は BillingResponseCode.OK
以外のレスポンスを返すことがあります。これらのレスポンス コードは、次のように処理することを検討してください。
ERROR
: これは内部エラーです。取引を進めたり外部ウェブサイトを開いたりしないでください。次回ユーザーをアプリ外に誘導しようとしたときに、showExternalOfferInformationDialog()
を呼び出して情報ダイアログを表示して再試行します。FEATURE_NOT_SUPPORTED
: 外部オファーの API が、現在のデバイスの Google Play ストアでサポートされていません。取引を進めたり外部ウェブサイトを開いたりしないでください。USER_CANCELED
: 外部ウェブサイトを開きません。次回ユーザーをアプリ外に誘導しようとしたときに、showExternalOfferInformationDialog()
を再度呼び出して情報ダイアログを表示します。BILLING_UNAVAILABLE
: 取引が外部オファーの対象ではないため、このプログラムでは続行できません。これは、ユーザーがこのプログラムの対象国に居住していないか、アカウントがプログラムに正常に登録されていないことが原因です。後者の場合は、Google Play Console で登録ステータスを確認してください。DEVELOPER_ERROR
: リクエストでエラーが発生しています。先に進む前に、デバッグ メッセージを使用してエラーを特定および修正してください。NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE
: 適切な再試行ポリシーで処理する必要がある一時的なエラーです。SERVICE_DISCONNECTED
の場合は、Google Play との接続を再確立してから再試行してください。
外部特典をテストする
外部オファーの統合をテストするには、ライセンス テスターを使用する必要があります。ライセンス テスター アカウントによって開始された取引については、請求は発生しません。ライセンス テスターの設定について詳しくは、アプリ ライセンスを使用してアプリ内課金をテストするをご覧ください。
次のステップ
アプリ内統合が完了すると、バックエンドを統合する準備が整います。