Store integration - Meta Horizon | brainCloud Help Center

Overview

This guide demonstrates how to implement a complete IAP flow using Meta's Horizon Platform SDK for client-side purchases and brainCloud's VerifyPurchase() API for server-side verification. The integration ensures secure, server-validated transactions that prevent fraud and unauthorized purchases.

Prerequisites

Required SDKs

Unity 2022.3.15f1 or later
Meta XR Platform SDK (UPM version)
brainCloud Unity SDK

Required Accounts

Meta Developer account with app configured
brainCloud account with app and product configuration
Meta Quest device for testing

Step 1: Meta Developer Account Setup

1.1 Create/Configure Your App

Navigate to Meta Developer Dashboard
Create a new app or select an existing app
Note your App ID - you'll need this for Unity configuration

1.2 Enable In-App Purchase Services

Go to Development -> All Platform Services
Click Add-ons -> Add Service
Enable IAP functionality for your app

1.3 Add Test Users

Navigate to Development -> Test Users
Add test user accounts for development testing
These users can make test purchases without real charges

1.4 Configure Product SKUs

Navigate to Monetization -> Add-ons section in your app dashboard
Click Create Add-on
For each product, configure:
1. SKU (e.g., test_sku_1) - must match Unity code
2. Name - display name shown to users
3. Description - product description
4. Price - set pricing in USD or other currencies
5. Type - Consumable, Durable (Non-Consumable)
6. Assign Add-on - Assign test users to the add-on

Important: SKU identifiers must exactly match between the Meta Dashboard, Unity code, and brainCloud configuration.

1.5 Complete Data Use Checkup (DUC)

Go to Requirements -> Data Use Checkup
Add required permissions:
1. User ID - required for authentication
2. In-App Purchases - required for IAP transactions
Complete and submit the DUC form

1.6 Configure App Metadata (Optional)

If using downloadable content (DLC):

Go to Distribution -> App Submissions -> App Metadata -> Specs
Mark app as requiring Internet connection

Note: This step only applies if you're using downloadable content or asset files. For standard IAP consumables/non-consumables, you can skip this.

Step 2: Unity Project Configuration

2.1 Install Meta XR Platform SDK

Open Meta XR Downloads
Find Meta XR Platform SDK (UPM)
Click Add to My Assets (redirects to Asset Store)
In Unity, open Window -> Package Manager
Switch dropdown to My Assets
Find Meta XR Platform SDK and click Install
If prompted to update OVRPlugin, accept and restart Unity

2.2 Install brainCloud Unity SDK

Add brainCloud package via Package Manager
Follow brainCloud documentation for UPM setup

2.3 Configure Oculus Platform Settings

Open Meta -> Platform -> Edit Settings -> Oculus
Under Platform Settings section:
1. Enter your Oculus App ID from Meta Dashboard
2. Log in to the Meta app test user with credentials

2.4 Add Scripting Define Symbol (optional)

Open Edit -> Project Settings -> Player
Select Android platform tab
Expand Other Settings
Find Scripting Define Symbols
Add OCULUS_PLATFORM_SDK (comma-separated if other symbols exist)

This define symbol enables conditional compilation for Meta Platform SDK code and allows simulation mode when SDK is not available.

2.5 Switch to Android Build Target

Open File -> Build Settings
Select Android platform
Click Switch Platform
Configure Android build settings:
1. Minimum API Level: Android 10.0 (API level 29) or higher
2. Target API Level: Latest available

Step 3: brainCloud Configuration

3.1 Create brainCloud App

Log into brainCloud Portal
Create new app or select existing app
Note the following credentials from Core App Info -> Application IDs, it will be used in your Unity project code:
1. App ID
2. App Secret
Navigate to Oculus tab within the Configure Platforms section, then put your Meta App ID and App Secret in the designated fields.

3.2 Add Product Definitions

For each product configured in Meta Dashboard:

Go to Design -> Marketplace -> Products
Click Create Product
Configure product:
1. Item ID - internal brainCloud identifier
2. Title - product name
3. Description - product description
4. Type - Consumable, Non-Consumable, or Subscription
5. Currency - virtual currency to award on purchase (optional)
Map to Meta SKU:
1. Under Add Platform
2. Select Meta Horizon store
3. Enter exact SKU from Meta Dashboard
4. Map brainCloud Product ID to Meta SKU
  Critical: The SKU in Meta Dashboard must exactly match the mapped SKU in brainCloud for verification to succeed.

Step 4: Implementation Code Examples

4.1 MetaPlatform methods

Key Responsibilities:

Initialize Meta Platform SDK
Verify user entitlement
Retrieve logged-in user ID and proof (nonce)
Launch purchase checkout flow
Handle purchase success/failure callbacks

Critical Code Sections:
Initialization:

void Start()
{
#if OCULUS_PLATFORM_SDK
    Core.AsyncInitialize().OnComplete(m => {
        if (m.IsError) {
            Debug.LogError("Meta Platform Init Failed: " + m.GetError().Message);
        } else {
            Entitlements.IsUserEntitledToApplication().OnComplete(e => {
                if (!e.IsError) {
                    GetLoggedInUser();
                }
            });
        }
    });
#else
    // Simulation mode for testing without SDK
    RefreshAuthentication();
#endif
}

Purchase Flow:

public void LaunchPurchaseFlow(string sku)
{
#if OCULUS_PLATFORM_SDK
    IAP.LaunchCheckoutFlow(sku).OnComplete(m => {
        if (!m.IsError) {
            var purchase = m.Data;
            // Emit success event with receipt data
            OnPurchaseSuccess?.Invoke(
                purchase.Sku, 
                purchase.ID, 
                _loggedInUserId
            );
        }
    });
#endif
}

4.2 BrainCloud methods

Key Responsibilities:

Initialize brainCloud SDK wrapper
Authenticate user with Oculus credentials
Call VerifyPurchase() with metaHorizon store ID
Handle verification success/failure

Critical Code Sections:
Oculus Authentication:

public void AuthenticateOculus(string userId, string nonce)
{
    _bc.AuthenticateOculus(userId, nonce, true, 
        (response, cbObject) => {
            Debug.Log("braincloud Auth Success");
            OnStatusChanged?.Invoke("braincloud authenticated");
        }, 
        (status, code, error, cbObject) => {
            Debug.LogError($"Auth Failed: {status} {code} {error}");
        }
    );
}

Purchase Verification:

public void VerifyMetaPurchase(string sku, string transactionId, string metaUserId)
{
    // Construct receipt data for metaHorizon store
    Dictionary<string, object> receiptData = new Dictionary<string, object>();
    receiptData["userId"] = metaUserId;
    receiptData["sku"] = sku;
    receiptData["transactionId"] = transactionId;
    receiptData["consumeOnVerify"] = true; // true for consumables

    string receiptJson = JsonWriter.Serialize(receiptData);

    _bc.AppStoreService.VerifyPurchase(
        "metaHorizon",  // Store ID
        receiptJson,     // Receipt data JSON
        (response, cbObject) => {
            Debug.Log("Purchase Verified! Rewards granted.");
            OnStatusChanged?.Invoke("Purchase verified");
        },
        (status, code, error, cbObject) => {
            Debug.LogError($"Verification Failed: {status} {code} {error}");
        }
    );
}

Step 5: Testing

5.1 Quest Device Testing

Prerequisites:

Quest device in Developer Mode
Test user logged into Quest
USB connection or wireless ADB setup

Testing Steps:

Build and deploy to Quest device
Launch app on Quest
Verify Meta Platform initialization in logs
Test authentication flow
Initiate test purchase
Complete purchase flow
Verify brainCloud verification logs
Check rewards granted in brainCloud portal

Protip: The DllNotFoundException: ovrplatform assembly error indicates that the native ovrplatform library is not available for the current runtime environment, since the Meta Platform native libraries are exclusively compatible with Windows and Android platforms.

For a complete code example, please refer to our Unity GitHub repository here.