[Closed Beta] Basic receipt validation

For:
Last update:

beta_feature.png

At a glance: Get basic receipt validation to measure revenue from in-app purchases and get accurate ROAS measurements. Contact your CSM to join the close beta.

About basic receipt validation

Advertisers can use basic receipt validation to validate and measure in-app purchases from Google Play and the App Store and get accurate ROAS measurements.

Basic receipt validation is free of charge to all account plans.

Note

Consider using ROI360 in-app purchases (IAP) and subscription revenue measurement to measure:

  • All revenue from in-app purchases of products and subscriptions managed through either Google Play Console (Android) or App Store Connect (iOS).
  • Refunds.
  • Pending and deferred transaction revenue (Android).
  • Subscription-related events that happen inside or outside your app (renewals, conversions from trial, cancelations, and more).

The ROI360 solution also:

  • Makes sure no duplicate transactions are recorded. For iOS, this also ensures that no duplications are recorded for family sharing.
  • Allows AppsFlyer to forward Apple App Store transactions to you (the advertiser).
  • Provides True Revenue data, meaning net revenue data that takes into account store commission and taxes.

Basic receipt validation integration workflow

Precisely follow the order of the setup instructions listed in the table below to ensure optimal accuracy and reporting of purchase revenue. Failing to do so can result in permanent reporting inaccuracies. Full details for each step are included in the tabs following the table.

Step Tasks
1

Generate the Google Play key for receipt validation.
2

Generate the iOS App Store keys for receipt validation.
3

Implement the validateAndLogInAppPurchase function in the AppsFlyer SDK for Android and iOS.

Note: Calling this function generates an af_purchase in-app event. As such, don't generate an af_purchase event when validating. Doing so results in duplicate revenue events.
4

Release the Android and iOS app versions with the validateAndLogInAppPurchase function.

Step 1: Generate Google Play key for receipt validation

Before you start:

  • Setting up basic receipt validation consists of steps performed in Google Cloud Platform, and in the AppsFlyer UI. We recommend you keep tabs to Google Cloud Platform and AppsFlyer open throughout the setup.
  • Setup in the AppsFlyer UI requires admin permissions.

Follow the instructions in the tabs below to generate and upload the Google Play key:

1.1 Link your Google Play Developer Account to your Google Cloud Project

  1. In the Google Play Console, go to your Google Play Developer Account.
  2. Link the account to your Google Cloud project. For instructions, see this Google help topic.
  3. Enable the Google Play Developer API. For instructions, see this Google help topic.

1.2 Create service account

  1. Go to Google Cloud and open the project you just linked in 1.1.
  2. Under your project go to IAM and Admin > Service Accounts, and click Create service account.
    01.png
  3. In the Create service account page complete the Service account details step. Remember the service account name; you'll need it in step 1.4.
    02.png
  4. Click Create and continue.
  5. In the Grant this service account access to the project step, select the  Pub/sub subscriber role.
    03.png
  6. Click Continue > Done.

1.3 Download account private key.

  1. In the Service Accounts page, find the relevant service account, and click  ellipsis.png  and than Manage keys.
    08.png
  2. In the Keys tab of the service account page click ADD KEY > Create new key.
    10.png
  3. In the Create private key dialog, select the JSON key type.
  4. Click Create. The private key JSON file is downloaded.
  5. In AppsFlyer, from the side menu, select Settings > Revenue Settings.
  6. Select your app from the list.
  7. In the Basic receipt validation tab, click upload-2.png to upload the JSON file.

1.4 Set API access permissions

  1. In the Google Play Console, go to Users and permissions.
  2. In the Users and permissions list, find the service account you created in 1.2, and click Manage.
    14.png
  3. In the Permissions section, go to the Account permissions tab, and select both:
    • View financial data.
    • Manage orders and subscriptions.

    15.png
  4. Click Invite user and then Send invitation.

1.5 Validate and configure Basic receipt validation

  1. In AppsFlyer, in the Basic receipt validation tab, click Validate key to make sure the JSON file you uploaded is correct.
    Note:
    • After setting service account credentials and permissions, it can take up to 24 hours to be able to use them. This may cause you to receive errors when trying to validate the key or perform a validation test.
    • To work around this 24 hour wait time, in the Google Play Console, go to any application, navigate to Monetize > Products > Subscriptions/In-app products, and change something. For example, edit the description of your product and save it. This should instantly update the account credentials and permissions. You can then undo the changes.
  2. Turn on Validate purchases with Google Play.
  3. Click Save.

Step 2: Generate iOS App Store keys for receipt validation

Before you start:

  • Setting up basic receipt validation consists of steps performed in App Store Connect and in the AppsFlyer UI. Keep tabs to both App Store Connect and AppsFlyer open during setup.

  • Setup in the AppsFlyer UI requires admin permissions.

To configure basic purchase receipt validation:

  1. In App Store Connect, go to Apps and select the relevant apps.
  2. In App Store Connect, go to Users and Access > Keys and from the Key Type list, select App Store Connect API.
  3. Click + to generate an API key.
  4. Enter a name for your API key, and for Access, enter the role "Admin," "App manager," or "Developer".
  5. Click Generate.
  6. Click Download to download the API key. Note: You can only download the key once.
  7. In AppsFlyer, from the side menu, select Settings > Revenue Settings.
  8. Select your app from the list.
  9. In the Basic receipt validation tab, click upload-2.png to upload the p8 file.
  10. In App Store Connect, copy the Key ID of the key you just generated, and paste it in the AppsFlyer Basic receipt validation setting for Key ID.
  11. In App Store Connect, copy the Issuer ID, and paste it in the AppsFlyer Basic receipt validation setting for Issuer ID.
  12. In AppsFlyer Basic receipt validation settings, click Validate keys to make sure the keys you entered are correct.
  13. Turn on Validate purchases with the Apple App Store.
  14. Click Save.

Step 3: Implement validateAndLogInAppPurchase (Beta) function

Implementing the validateAndLogInAppPurchase(Beta) function for iOS and Android enables your app to record in-app purchases made in Google Play and the App Store.

To integrate the function:

  1. Tell your Android developer to follow their AppsFlyer Android SDK instructions.
  2. Tell your iOS developer to integrate the AppsFlyer iOS SDK instructions.

Note: For apps built using the Unity framework, developers should refer to the Android and iOS SDK instructions. 

Step 4: Release app version with validateAndLogInAppPurchase function

Before your developer releases the new app version with the validateAndLogInAppPurchase function implemented, make sure that:

  • All previous steps have been completed.
  • Any Sandbox parameters from the testing environment are removed.
  • The in-app events you want to capture as purchases aren't blocked by one of the Validation Rules you may have configured in AppsFlyer.

Reference

In-app purchase event and parameters

Below you can read about the in-app purchase event and its parameters. See the event parameter dictionary for an explanation of the included parameters.

The event recorded for in-app purchases is: af_purchase

All purchase events:

  • Are considered S2S events.
  • Are accessible in raw data reports (as organic or non-organic in-app events).
  • Can be sent via postbacks to partners.
  • Can be used in SKAN Conversion Studio.

The event includes the following parameters:

  • af_environment: Either sandbox or production (iOS only)
  • af_validation_type: basic
  • af_product_id
  • af_transaction_id (iOS only)
  • af_purchase_token (Android only)
  • af_revenue
  • af_currency
  • af_validated: Either true or false
  • af_store: Either  app_store or google_play
  • Other parameters provided by the developer in the request
  • appsflyer_id
  • customer_user_id
  • advertising_id
  • idfa
  • idfv
  • att
  • os version
  • app version
  • ip
  • geo
  • custom data

Receipt validation flow

The receipt validation flow is as follows:

  1. The user performs an in-app purchase.
  2. The app store notifies the app of the successful purchase.
  3. The app developer calls the SDK Basic receipt validation function: validateAndLogInAppPurchaseInAppPurchase
  4. The SDK calls the AppsFlyer validation service.
  5. AppsFlyer validates the purchase to make sure it is not fraudulent.
  6. Upon success, AppsFlyer internally creates a regular af_purchase event. Otherwise, the created event is tagged as fraudulent (available via Protect360). 
  7. The AppsFlyer validation service transfers the response to the SDK.
  8. The SDK transfers the receipt validation response to the app (either success or fail).
    If receipt validation fails, the event displays in the blocked in-app events raw-data report (available to Protect360 subscribers). 

Traits and limitations

Trait Remarks
Supported stores
  • Google Play
  • App Store
  • For any other (third-party) stores, you must manually send in-app purchase events.
iOS sandbox apps
  • For iOS sandbox apps, meaning apps that are not live in the App Store, receipt validation requires some additional code.