Android Setup Guide

Prerequisites#

Before you can implement and test in-app purchases on Android, you must complete these essential steps:

1. Google Play Developer Account#

• Register for a Google Play Developer account ($25 one-time fee)
• Complete identity verification
• Accept all developer agreements
• Set up payment profile in Google Play Console

2. Merchant Account Setup#

• Navigate to Setup → Payments profile
• Link a Google Payments Merchant account
• Complete tax information
• Verify banking details
• Important: Products won't work without a verified merchant account

Google Play Console Configuration#

1. Create Your App#

• Sign in to Google Play Console
• Click "Create app"
• Fill in app details (name, default language, app/game category)
• Select free or paid app
• Accept the Developer Program Policies

2. Upload Your App#

You must upload at least one APK/AAB to create in-app products:

• Go to Release → Testing → Internal testing
• Create a new release
• Upload your signed APK or App Bundle
• Save and review the release
• Roll out to internal testing

3. Create In-App Products#

• Navigate to Monetization → In-app products
• Click "Create product"
• Choose your product type:
  • Managed Products: One-time purchases or consumables
  • Subscriptions: Recurring subscriptions (requires separate setup)

4. Configure Product Details#

For each product, provide:

• Product ID: Unique identifier (e.g., premium_upgrade, coins_100)
• Name: Display name for users
• Description: Product description
• Price: Set price for each country/region
• Set product status to Active

5. Configure Subscriptions (if applicable)#

• Navigate to Monetization → Subscriptions
• Create subscription with base plans and offers
• Configure billing period (weekly, monthly, yearly, etc.)
• Set up free trials or introductory pricing if desired
• Add subscription benefits for user display

Android Project Configuration#

1. Minimum SDK Requirements#

The OpenIAP Android core library (openiap-google) requires minSdk 23 (Android 6.0) with Google Play Billing 9.1.0. Each framework library may require a higher minimum — check the framework-specific setup page for the exact value.

2. Update build.gradle#

Add the OpenIAP Android dependency. Its manifest already declares the billing and internet permissions, so your app adds neither.

// build.gradle.kts
dependencies {
    implementation("io.github.hyochan.openiap:openiap-google:4.0.1")
}

// Or build.gradle (Groovy)
dependencies {
    implementation 'io.github.hyochan.openiap:openiap-google:4.0.1'
}

Check the latest version at Maven Central.

3. R8 and ProGuard#

No rules to add. From 3.6.1, each store artifact ships the keep rules its billing SDK needs, so minified release builds work as they are.

Testing Setup#

1. Set Up License Testing#

• In Google Play Console, go to Setup → License testing
• Add tester email addresses (Gmail accounts)
• Set license response to LICENSED
• Save changes

2. Create Test Track#

• Use Internal testing track for fastest updates
• Add testers by email or Google Groups
• Share opt-in link with testers
• Testers must accept the invitation

3. Testing Best Practices#

• Use the same Google account on the test device as added to license testing
• Ensure the app is downloaded from Play Store (via test track)
• Test purchases will show "(Test)" in the purchase dialog
• Test cards are automatically used - no real charges occur

Integration with OpenIAP Libraries#

To implement in-app purchases on Android, use one of the OpenIAP specification libraries:

• expo-iap - For Expo projects (Expo Modules)
• react-native-iap - For React Native projects (Nitro Modules)
• flutter_inapp_purchase - For Flutter projects
• kmp-iap - For Kotlin Multiplatform projects
• maui-iap - For .NET MAUI projects
• godot-iap - For Godot 4.x projects

These libraries implement the OpenIAP Client Protocol and handle Android-specific requirements — refer to each library's documentation for implementation details.

Android-Specific Requirements#

Purchase Acknowledgment#

Android requires acknowledging purchases within 3 days. Unacknowledged purchases are automatically refunded by Google Play. In OpenIAP SDKs the completion order is: verify with a trusted verifier (your backend or IAPKit), grant and persist the entitlement so it survives a restart, then acknowledge through finishTransaction.

Consumable Products#

Consumable products must be consumed before they can be purchased again. This prevents duplicate purchases of items like coins or lives. Consumption is the finishTransaction call with isConsumable: true.

Purchase Verification#

Always verify purchases through a trusted verifier that calls the Google Play Developer API — either your backend or IAPKit — to prevent fraud and ensure purchase validity. See the Purchase Verification guide.

Billing Choice and Billing Programs#

OpenIAP's Android core uses Google Play Billing 9.1.0. Billing Choice is exposed through the Billing Programs API with BillingProgramAndroid.BillingChoice in native Kotlin and 'billing-choice' in TypeScript.

• Enable Billing Choice in initConnection with enableBillingProgramAndroid. Also set billingChoiceScreenTypeAndroid to the renderer configured in Play Console. It defaults to GOOGLE_RENDERED.
• Check availability and renderer type with isBillingProgramAvailableAndroid.
• For developer-rendered screens, fetch Play assets with getBillingChoiceInfoAndroid.
• Create reporting details with createBillingProgramReportingDetailsAndroid and pass 'in-app' or 'external-link' as the developer billing type when required by your flow.
• For developer-rendered in-app flows, create an IN_APP reporting token and show the mandatory information dialog with showBillingProgramInformationDialogAndroid.
• For developer-rendered external-link flows, generate an EXTERNAL_LINK token and pass it to launchExternalLinkAndroid.

Subscription Management#

Subscriptions require special handling including:

• Grace periods for payment failures
• Upgrade/downgrade proration
• Subscription status verification
• Renewal notifications

OpenIAP libraries handle these Android-specific requirements automatically. Consult the library documentation for your chosen framework to ensure proper implementation.

Common Issues#

Products Not Loading#

Problem: fetchProducts() returns empty array

Solutions:

Check Prerequisites:#

• Verify merchant account is set up and verified
• Ensure app is uploaded to at least internal testing track
• Confirm products are set to "Active" status
• Wait 2-24 hours after creating products for propagation

Verify Configuration:#

• Product IDs match exactly (case-sensitive)
• App package name matches Play Console
• Version code in app ≥ version in Play Console
• App is signed with the same certificate

Purchase Flow Issues#

Problem: "This item is not available" error

Solution:

• Test on real device (not emulator)
• Download app from Play Store test track
• Use test account added to license testing
• Clear Play Store cache and data

Subscription Issues#

Problem: Subscriptions not appearing

Solution:

• Query subscriptions separately with type: 'subs'
• Ensure subscription is fully configured with base plans
• Check if country/region pricing is set
• Verify subscription benefits are added

Production Checklist#

• ✅ Server-side receipt validation implemented
• ✅ Purchase acknowledgment within 3 days
• ✅ Proper error handling for all purchase states
• ✅ Restore purchases functionality
• ✅ Network error retry logic
• ✅ Obfuscated user/profile IDs for fraud prevention
• ✅ Analytics tracking for purchase events
• ✅ Clear purchase flow UI/UX
• ✅ Refund handling process
• ✅ Subscription management UI (if applicable)

Best Practices#

• Always validate purchases through your backend or IAPKit using the Google Play Developer API
• Implement exponential backoff for network retries
• Cache product information locally for offline display
• Show clear pricing and subscription terms
• Handle grace periods for subscription billing issues
• Implement proper subscription upgrade/downgrade flows
• Test thoroughly with different Google accounts
• Monitor purchase metrics in Play Console