Guides

Migration from OSP to SDK integration

Suggest Edits

Overview

This guide explains how to migrate from the One-Step Payment (OSP) integration to the new Android Billing SDK integration. With the new SDK, you replace the URL-based billing flow and external web callbacks with a more integrated client that connects directly to the AppCoins Wallet.

📘

Note

Before you begin, please review the Android Billing SDK Documentation to correctly implement all the necessary code changes.

Integration specifications

OSP Integration (Current Implementation)

  • Billing Flow:
    • Generate a signed OSP URL on your server.
    • Launch an Intent using the URL.
    • AppCoins Wallet processes the payment.
    • A POST callback is sent to your web service endpoint.
    • Your server validates the transaction before giving the product.
  • Key Characteristics:
    • Uses URL-based payment calls.
    • Requires a server-side endpoint and URL signature generation.
    • The wallet is invoked externally (via Intent) and the app is notified through a callback.
    • Simple user acquisition without any major features.
    • Doesn't support any product type except Consumables.

Android Billing SDK Integration (New Implementation)

  • Billing Flow:
    • Set up a connection with the Android Billing SDK via an AppcoinsBillingClient.
    • Query products directly from Aptoide Connect.
    • Start a purchase flow by launching the AppCoins Wallet via the SDK.
    • Process the purchase result with an in-app callback (PurchasesUpdatedListener).
    • Validate the Purchase to ensure the legitimacy of it and avoid fraud.
    • Consume the purchase so that the item can be repurchased if needed.
  • Key Characteristics:
    • Provides a seamless in-app billing experience.
    • Eliminates the need for external URL generation and web callbacks.
    • Uses native Android components and asynchronous callbacks.
    • D2C features for improved user acquisition and rewarding.
    • Supports seamslessly Subcription type products.

Key Differences Between OSP and SDK integrations

The key differences between the OSP and SDK integrations are:

AspectOSP IntegrationAndroid Billing SDK Integration
Payment InvocationLaunches an Intent with a signed URLUses a Billing client to start the purchase flow
Transaction HandlingWeb service callback on transaction completionIn-app callback via PurchasesUpdatedListener
Server InvolvementMust generate a signed URL on a serverMinimal server-side logic; public key is provided via console; RTDN can be used to notify server-side of Purchases states
Product QueryingNot required; product details are registered in Aptoide Connect or fetched manuallyProducts are queried directly from Aptoide Connect via querySkuDetails
Purchase ConsumptionNot applicable (handled via callback)Must explicitly consume purchases using consumeAsync
MaintenanceRequires manual updates and adjustments for breaking change featuresManaged within the SDK, reducing maintenance efforts

Additional Considerations

Pending Purchases

To handle correctly any pending Purchase, after the connection setup to the Billing Client, immediately check for any pending Purchases using the queryPurchases method and consume the ones that are validated. This ensures that any incomplete transactions are properly handled.

Threading

The Android Billing SDK requires to some calls to be made in the IO threads, especially network calls. Take special attention to those that require this change so the UI of your application remains fluid and responsive.

Purchase identifcation

Use the developerPayload (for example, a user ID or an internal order ID) during the purchase flow to further link the Purchase to a User.

Testing

Use the provided test credentials and sample implementations (such as the Diceroll SDK sample) to verify that the new integration works correctly before rolling it out to production.

FAQ

What happens if the billing service isn’t ready?

The SDK provides an isReady method on the billing client to confirm the readiness of the Billing Client. Ensure you check this before initiating any purchase flow or query for Purchases/Sku Details.

Do I still need to manage a server-side callback?

No. The Android Billing SDK handles transaction updates within the app via the PurchasesUpdatedListener. This eliminates the need for a separate server-side callback endpoint. You can use the RTDN's to verify changes in the Subscriptions and the Voided Purchases.

How do I consume a purchase?

Use the consumeAsync method provided by the SDK to consume purchases. If a purchase isn’t consumed within 48 hours, it will be automatically refunded.

How often should I update the version of the SDK?

The update of the SDK version is not mandatory, but keep in mind that every new release brings important features and improvements in the SDK. Try to keep the version up-to-date since it mostly requires only a bump in the version itself.

How can I avoid fraud and ensure the legitimacy of the Purchases?

To ensure that the Purchases you receive in your Client Application are legitimate, follow the guidelines in the In-App Purchase Validation page.

Updated 2 days ago