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
The Meta Horizon Billing Compatibility 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.
The following sections show you how to configure your dependencies to install a specific version of the SDK. Use version 2.0.0 or later to use the latest features.
Option A: Add the version 2.0.0 or later dependency to Gradle
In app/build.gradle.kts, create variables for the SDK versions above the dependencies block:
val horizonBillingCompatibilitySdkVersion = "2.0.0"
val coreKotlinVersion = "0.2.0"
At the end of the dependencies block, add the following packages:
The variable declaration and dependencies block should now look like this:
val horizonBillingCompatibilitySdkVersion = "1.1.2"
val androidPlatformSdkVersion = "72"
dependencies {
...
implementation("com.meta.horizon.billingclient.api:horizon-billing-compatibility:$horizonBillingCompatibilitySdkVersion")
implementation("com.meta.horizon.platform.ovr:android-platform-sdk:$androidPlatformSdkVersion")
}
Sync your project with Gradle to download the packages.
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:
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.
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;
}
}
}
Test with Meta Spatial Simulator
Starting with version 2.0.0, the Meta Horizon Billing Compatibility SDK can be used with the Meta Spatial Simulator. This allows you to test your billing integration in the simulator environment without needing a physical headset.
When developing monetization features with the Horizon Billing Compatibility SDK, you should use test user accounts rather than your personal developer account. Test users provide a clean environment for testing purchase flows and allow you to:
Test purchase flows with test credit cards that simulate successful and failed transactions
Reset entitlements to repeat purchase testing without real transactions
Test with multiple accounts to verify multi-user scenarios
Prerequisites
Before testing monetization features, ensure you have:
Uploaded an APK: Your app must have at least one APK uploaded to a release channel (Alpha, Beta, or RC). Monetization APIs require a package to function.
Created in-app products: Set up your add-ons (consumables, durables, or subscriptions) in the Developer Dashboard.
Created test users: Create test user accounts in the Developer Dashboard under Test Users. (If you don’t see this option, click View All at the top of the left navigation to open the Org Manager.) For detailed instructions, see Test Users.
Set up test payment methods
Test users can purchase in-app items without using real money. To set up test payment methods:
Log in to your headset or the Meta Horizon mobile app as the test user.
Add one of the following test credit card numbers:
4111 1177 1155 2927: Always succeeds
4111 1193 1540 5122: Fails at sale
When entering test credit cards, provide any 5-digit zip code, any future expiration date, and 111 for the security code.
Important: Do not use real credit cards with test users. Real credit cards will be charged as regular transactions. Always use the test credit card numbers provided.
Manage add-on entitlements
After testing purchases, you can reset a test user’s entitlements to repeat the purchase flow: