Visão geral:

Este documento fornece um guia abrangente sobre como implementar eventos de assinatura usando o Singular SDK. Ele cobre o rastreamento de eventos de assinatura no aplicativo em várias plataformas, integração de eventos de servidor para servidor (S2S) e integrações de terceiros como RevenueCat e Adapty.

O Singular permite-lhe acompanhar as suas subscrições e renovações na sua aplicação, fornecendo informações sobre o comportamento do utilizador e a geração de receitas. A atribuição de assinatura do Singular oferece métodos robustos para rastrear eventos de assinatura, garantindo uma coleta de dados precisa e em tempo real.

Implementar a gestão do estado da subscrição na aplicação

Ao integrar a biblioteca de faturação do Google Play e o StoreKit da Apple, pode consultar informações sobre a subscrição e gerir o estado da subscrição diretamente no dispositivo. Essa configuração permite a integração com um dos métodos de implementação do Singular. Abaixo estão exemplos de trechos de código que demonstram implementações simples da Biblioteca de Faturamento e do StoreKit para servir como exemplos práticos. Deve modificar estes exemplos na Produção para se adaptarem ao código e ao modelo de subscrição da sua aplicação.

Android: integração da biblioteca de faturação do Google Play

1. Adicionar a biblioteca de faturação ao seu projeto

Adicione a configuração da biblioteca de faturação do Google Play no seu build.gradle

implementation 'com.android.billingclient:billing:6.0.1'

2. Configurar produtos e subscrições na aplicação

Configure os seus produtos in-app e itens de subscrição na Consola do Google Play

3. Consultar informações de subscrição

Utilize o BillingClient para consultar o histórico de compras e o estado da subscrição na sua aplicação.

val billingClient = BillingClient.newBuilder(context)
  .setListener(purchaseUpdateListener)
  .enablePendingPurchases()
  .build()
billingClient.startConnection(object : BillingClientStateListener {
  override fun onBillingSetupFinished(billingResult: BillingResult) {
    if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
        // The billing client is ready, you can now query subscription information asynchronously


        billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {result, subscriptionList ->
            if (result.responseCode == BillingClient.BillingResponseCode.OK && subscriptionList != null) {
                // Handle the retrieved subscription list


                subscriptionList.forEach { purchase ->
                    // Process each subscription purchase


                }
            } else {
                // Handle error in queryPurchasesAsync


            }
        }
    } else {
       // Handle error on setup finished


    }
  }
  override fun onBillingServiceDisconnected() {
    // Retry connection after a delay if the service gets disconnected


    Handler(Looper.getMainLooper()).postDelayed({
        billingClient.startConnection(this)
    }, 3000)
  }
})
// Remember to properly disconnect the billing client in your activity/fragment lifecycle


override fun onDestroy() {
    billingClient.endConnection()
    super.onDestroy()
}

BillingClient billingClient = BillingClient.newBuilder(context)
  .setListener(purchaseUpdateListener)
  .enablePendingPurchases()
  .build();
BillingClientStateListener billingClientStateListener = new BillingClientStateListener() {
  @Override
  public void onBillingSetupFinished(BillingResult billingResult) {
    if (billingResult.getResponseCode() == BillingClient.BillingResponseCode.OK) {
        // The billing client is ready, you can now query subscription information asynchronously


        billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS, (result, purchasesList) -> {
            if (result.getResponseCode() == BillingClient.BillingResponseCode.OK && purchasesList != null) {
                // Handle the retrieved subscription list


                for (Purchase purchase : purchasesList) {
                    // Process each subscription purchase


                }
            } else {
                // Handle error in queryPurchasesAsync


            }
        });
    } else {
        // Handle error on setup finished


    }
    }
  @Override
  public void onBillingServiceDisconnected() {
    // Retry connection after a delay if the service gets disconnected


    new Handler(Looper.getMainLooper()).postDelayed(() -> billingClient.startConnection(billingClientStateListener), 3000);
  }
};
billingClient.startConnection(billingClientStateListener);
@Override
protected void onDestroy() {
  super.onDestroy();
  if (billingClient != null) {
    billingClient.endConnection();
  }
}

iOS: Integrar o StoreKit

1. Implementar o StoreKit

Integre a estrutura do StoreKit no seu aplicativo iOS.

2. Configurar produtos e subscrições in-app

Configure produtos in-app e itens de subscrição no App Store Connect

3. Consultar informações de subscrição

Utilize SKPaymentQueue e SKReceiptRefreshRequest para obter o estado da subscrição e as informações do recibo.

import StoreKit
class YourViewController: UIViewController, SKPaymentTransactionObserver {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Add the observer for payment transactions


        SKPaymentQueue.default().add(self)
        
        // Refresh the receipt to get the latest subscription information


        refreshReceipt()
    }
    func refreshReceipt() {
        let request = SKReceiptRefreshRequest()
        request.delegate = self
        request.start()
    }
    // Implement SKPaymentTransactionObserver methods


    func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction]) {
        for transaction in transactions {
            switch transaction.transactionState {
            case .purchased, .restored:
                // Handle the purchase or restore


                // You can check the transaction.transactionReceipt for receipt information


                break
            case .failed:
                // Handle the failed transaction


                break
            case .deferred:
                // Handle the deferred transaction


                break
            case .purchasing:
                // Transaction is in progress


                break
            @unknown default:
                break
            }
        }
    }
    // Implement SKRequestDelegate method


    func requestDidFinish(_ request: SKRequest) {
        // Receipt refresh request completed


        // Now you can use the updated receipt to check subscription status


    }
    func request(_ request: SKRequest, didFailWithError error: Error) {
        // Handle the error during the receipt refresh request


    }
}

Enviar eventos de subscrição a partir do Singular SDK

Quando o estado da assinatura muda nas implementações acima, um novo evento Revenue personalizado deve ser enviado ao Singular. NÃO use as funções IAP e NÃO envie um valor de recibo para o Singular. Siga o respetivo guia de implementação do SDK da Singular que você implementou em seu aplicativo para enviar um evento customRevenue() sem o recibo.

• SDK do iOS: use este método para enviar o nome do evento "subscription":

  (void)customRevenue:(NSString*)eventname currency:(NSString *)currency
          amount:(double)amount withAttributes:(NSDictionary*)attributes;

• Android SDK: utilize este método para enviar o nome do evento "subscription":

  Singular.customRevenue(String eventName, String currency, double
          amount, Map<String, Object> attributes)

• React Native SDK: utilize este método para enviar o nome do evento "subscription":

  static customRevenueWithArgs(eventName: string, currency: string,
          amount: number, args: SerializableObject): void;

• Unity SDK: utilize este método para enviar o nome do evento "subscription":

  SingularSDK.CustomRevenue(string eventName, string currency, double
          amount, Dictionary<string, object> attributes)

• Flutter SDK: utilize este método para enviar o nome do evento "subscription":

  Singular.customRevenueWithAttributes(String eventName, String currency, 
          double amount, Map attributes)

• Cordova SDK: utilize este método para enviar o nome do evento "subscription":

  SingularCordovaSdk.customRevenueWithArgs(String eventName, String currency, 
          double amount, JSONObject args)

Envio de eventos de subscrição S2S

Se preferir enviar eventos de assinatura em tempo real e gerenciar eventos de assinatura em seu back-end, você pode enviar eventos para a API REST do Singular.

Use o Event Endpoint para enviar eventos de assinatura para o Singular e certifique-se de incluir os parâmetros Revenue.

• Se você tiver implementado o SDK do Singular:
  • Você não deve enviar eventos de assinatura do SDK com esta opção
  • Não é necessário integrar-se ao ponto de extremidade S2S de lançamento (sessão)

Envio de eventos de assinatura via integração 3P

Se você estiver usando um serviço de terceiros para gerenciar assinaturas, esses fornecedores capturam dados de assinatura por meio de seus próprios métodos de integração. Em seguida, eles enviam eventos de assinatura para a API REST do Singular, que já está integrada em seus sistemas. Estas integrações requerem algumas configurações nas plataformas dos parceiros - consulte os respectivos guias abaixo:

• Integração do RevenueCat
• Integração Adapty

Eventos de assinatura

Vários eventos de assinatura diferentes podem ser enviados para o Singular. Observe que os nomes de eventos padrão da Singular são fornecidos quando aplicáveis abaixo (consulte a documentação relevante do SDK), mas nomes de eventos personalizados também podem ser usados, se desejado.