Neste guia, descrevemos como fazer a integração com as APIs para oferecer suporte a ofertas externas em apps e regiões qualificados. Para saber mais sobre o programa de ofertas externas, incluindo os requisitos de qualificação e o escopo geográfico, consulte os requisitos do programa.
Configuração da Biblioteca Play Faturamento
Para usar as APIs de ofertas externas, adicione a versão 6.2.1 ou mais recente da dependência da Biblioteca Play Faturamento ao seu app Android. Se você precisar migrar de uma versão anterior, siga as instruções no guia de migração antes de tentar implementar ofertas externas.
Conectar ao Google Play
As primeiras etapas do processo de integração são as mesmas descritas no
guia de integração de faturamento, com algumas modificações ao
inicializar o BillingClient
:
- É necessário chamar um novo método para indicar que você quer usar ofertas
externas:
enableExternalOffer
.
O exemplo abaixo demonstra a inicialização de um BillingClient
com estas
modificações:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build();
Depois de inicializar o BillingClient
, você precisa estabelecer uma conexão com o Google Play,
conforme descrito no guia de integração.
Ver disponibilidade
Seu app precisa confirmar se as ofertas externas estão disponíveis chamando
isExternalOfferAvailableAsync
.
Essa API vai retornar BillingResponseCode.OK
se houver ofertas externas disponíveis.
Consulte o processamento de respostas para mais detalhes sobre como seu app precisa
responder a outros códigos de resposta.
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.
}
});
Preparar um token de transação externa
Para informar uma transação externa ao Google Play, você precisa ter um token de transação
externa gerado pela Biblioteca Play Faturamento. Um novo token de transação externa
precisa ser gerado sempre que o usuário visita um site externo
pela API de ofertas externas. Para fazer isso, chame a
API createExternalOfferReportingDetailsAsync
. É preciso gerar esse token
imediatamente antes de o usuário ser direcionado para fora do app. Ele
nunca pode ser armazenado em cache e um novo precisa ser gerado sempre que o usuário for direcionado
para fora do app.
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.
}
});
Caixa de diálogo de informações para os usuários
Para fazer a integração com ofertas externas, o app qualificado precisa mostrar uma tela
de informações que ajude os usuários a entender que estão prestes a ser direcionados para um site externo. A tela de informações precisa ser mostrada aos usuários
chamando a API showExternalOfferInformationDialog
antes da vinculação a uma
oferta externa todas as vezes.
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);
Se esse método retornar BillingResponseCode.OK
, o app poderá direcionar o usuário para o site externo. Se o método retornar
BillingResponseCode.USER_CANCELED
, o app não poderá continuar abrindo o
site.
Informar transações ao Google Play
Todas as transações externas precisam ser informadas ao Google Play
chamando a API Google Play Developer do back-end. Transações externas
precisam ser informadas ao fornecer um
externalTransactionToken
recebido usando a API
createExternalOfferReportingDetailsAsync
. Se um usuário fizer várias
compras, você poderá usar o mesmo
externalTransactionToken
para informar cada compra. Para saber como informar uma
transação, consulte o guia de integração de back-end.
Processamento de respostas
Quando ocorre um erro, os métodos isExternalOfferAvailableAsync
,
createExternalOfferReportingDetailsAsync
e
showExternalOfferInformationDialog
podem retornar respostas diferentes de
BillingResponseCode.OK
. Considere processar esses códigos de resposta da seguinte maneira:
ERROR
: este é um erro interno. Não prossiga com a transação ou abra o site externo. Tente novamente chamandoshowExternalOfferInformationDialog()
para mostrar a caixa de diálogo de informações para o usuário na próxima vez que você tentar direcionar o usuário para fora do app.FEATURE_NOT_SUPPORTED
: as APIs de ofertas externas não têm suporte da Play Store no dispositivo atual. Não prossiga com a transação ou abra o site externo.USER_CANCELED
: não continua abrindo o site externo. ChameshowExternalOfferInformationDialog()
novamente para mostrar a caixa de diálogo de informações para o usuário na próxima vez que você tentar direcionar o usuário para fora do app.BILLING_UNAVAILABLE
: a transação não está qualificada para ofertas externas e, portanto, não pode continuar neste programa. Isso ocorre porque o usuário não está em um país qualificado para o programa ou sua conta não foi inscrita no programa. No segundo caso, verifique o status de registro no Play Console.DEVELOPER_ERROR
: há um erro na solicitação. Use a mensagem de depuração para identificar e corrigir o erro antes de continuar.NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE
: são erros temporários que precisam ser tratados com uma política de nova tentativa adequada. No caso deSERVICE_DISCONNECTED
, restabeleça uma conexão com o Google Play antes de tentar novamente.
Testar ofertas externas
Os testadores de licença precisam ser usados para testar a integração de ofertas externas. Você não vai receber cobranças por transações iniciadas por contas de testadores de licença. Consulte Testar o faturamento em apps com o licenciamento de apps para mais informações sobre como configurar testadores de licença.
Próximas etapas
Depois de concluir a integração no app, estará tudo pronto para integrar seu back-end.