Integrate Meta Horizon Billing Compatibility SDK

Updated: May 19, 2025

If you have an existing Android app that is integrated with the Google Play Billing Library, you can use the Meta Horizon Billing Compatibility SDK to port your app to the Meta Horizon Store with minimal changes (though there are known limitations). The SDK supports consumable, durable, and subscription in-app purchases (IAP). The Meta Horizon Billing Compatibility SDK is compatible with the Google Play Billing Library version 7.0.

Step 1. Add the SDK to your app

Android Platform SDK is deployed to Maven Central so it can be added to your app. In this step, you will add it to your project by editing app/build.gradle.kts to include the correct dependencies.

If your app uses Groovy (build.gradle instead of build.gradle.kts), read the build dependencies page for Groovy syntax.

In app/build.gradle.kts, create a variable for the Android Platform SDK version above the dependencies block:

 val androidPlatformSdkVersion = "72"
 val horizonBillingCompatibilitySdkVersion = "1.1.1"

At the end of the dependencies block, add the following package:

 implementation("com.meta.horizon.platform.ovr:android-platform-sdk:$androidPlatformSdkVersion")
 implementation("com.meta.horizon.billingclient.api:horizon-billing-compatibility:$horizonBillingCompatibilitySdkVersion")

The variable declaration and dependencies block should now look like this:

 val androidPlatformSdkVersion = "72"

 dependencies {
 ...
 implementation("com.meta.horizon.platform.ovr:android-platform-sdk:$androidPlatformSdkVersion")
 implementation("com.meta.horizon.billingclient.api:horizon-billing-compatibility:$horizonBillingCompatibilitySdkVersion")
 }

Sync your project with Gradle to download the packages.

GIF of the Gradle sync icon being clicked

Step 2. Add Kotlin support

Meta Horizon Billing Compatibility SDK is implemented in Kotlin and requires consuming apps to include the kotlin stdlib as a dependency. Android apps that have already integrated Kotlin may skip this step.

Open your project folder’s build.gradle file and add the kotlin-gradle-plugin:

 buildscript {
 	dependencies {
     	classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.21"
 	}
 }

Open your app folder’s build.gradle file and apply the kotlin-android plugin:

 apply plugin: 'kotlin-android'

Add a dependency on org.jetbrains.kotlin:kotlin-stdlib-jdk7. For example:

 dependencies {
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.1.21"
 }

Sync your project by selecting Sync Now at the top of your build.gradle file in your IDE.

If the build fails because “Starting in Kotlin 2.0, the Compose Compiler Gradle plugin is required when compose is enabled,” please refer to the “Composer Compiler Gradle plugin” on the Android developer site.

Step 3. Update import statements

Update Google Play Billing imports in your app’s codebase to use Meta Horizon Billing Compatibility SDK imports by replacing all instances of the com.android.billingclient.api prefix with the prefix com.meta.horizon.billingclient.api.

If any Meta Horizon Billing Compatibility SDK import statement is unresolved, that indicates it isn’t supported by the Meta Horizon Billing Compatibility SDK. Remove or modify its usage in the app to make it work with the Meta Horizon Store.

Step 4. Port Product Catalog from Google Play Store to Meta Horizon Store

Keep the SKUs for the in-app items on the Meta Horizon Developer Center the same as the product IDs on Google Play Console for the app. Otherwise, you will have to update the product IDs in your app as well.

You can follow the instructions available in Setting Up Add-Ons for more details on creating your Subscriptions, Consumables and Durables.

Step 5. Integrate User Age Category

Effective January 2024, for an app to be listed on the Meta Horizon Store, app owners are required to self-certify the intended user age group for their apps. Additionally, if your app is designed for mixed ages (under 13 or applicable age in user’s region, and 13+), you’re required to integrate the Get Age Category API. By complying with these requirements, you will meet the necessary criteria for listing your app on the Meta Horizon Store.

Integration of the User Age Category API requires use of the Platform SDK for Android.

You can use the queryAgeCategoryAsync method in the BillingClient class to get the user age category.

billingClient.queryAgeCategoryAsync(ageCategoryResponseListenerImpl)

Here is the AgeCategoryResponseListener that should be implemented.

public interface AgeCategoryResponseListener {
  // Called to notify that the query age category operation has finished.
  public void onQueryAgeCategoryResponse(
      BillingResult billingResult, @BillingClient.AgeCategory Integer ageCategory);
}

Here is an example implementation of AgeCategoryResponseListener.

public class AgeCategoryResponseListenerImpl implements AgeCategoryResponseListener {
  void onQueryAgeCategoryResponse(
      BillingResult billingResult, @BillingClient.AgeCategory Integer ageCategory) {
    if (billingResult.getResponseCode() != BillingResponseCode.OK) {
      // handle error
      return;
    }
    switch (ageCategory) {
      case CHILD:
        // handle children (10-12, or applicable age in user's region)
        break;
      case TEEN:
        // handle teens (13-17, or applicable age in user's region)
        break;
      case ADULT:
        // handle adults (18+, or applicable age in user's region)
        break;
      case UNKNOWN:
        // handle case where we don't know the age
        break;
    }
  }
}