Skip to content

README.md

Latest commit

 

History

History
285 lines (213 loc) · 10.4 KB

README.md

File metadata and controls

285 lines (213 loc) · 10.4 KB
Raw

mParticle Expo Test App

This app tests the Expo config plugin integration for the mParticle React Native SDK.

Setup

  1. First, build and pack the main library:

    cd ..
yarn install
yarn dev:pack

  2. Install dependencies in the test app:

    cd ExpoTestApp
npm install

  3. Update the API keys in app.json:

    {
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "deploymentTarget": "15.6"
          }
        }
      ],
      [
        "react-native-mparticle",
        {
          "iosApiKey": "YOUR_IOS_API_KEY",
          "iosApiSecret": "YOUR_IOS_API_SECRET",
          "androidApiKey": "YOUR_ANDROID_API_KEY",
          "androidApiSecret": "YOUR_ANDROID_API_SECRET",
          "logLevel": "verbose",
          "environment": "development",
          "iosKits": ["mParticle-Rokt"],
          "androidKits": ["android-rokt-kit"]
        }
      ]
    ]
  }
}

Running the App

iOS

npm run prebuild
npm run ios

Android

npm run prebuild
npm run android

Testing

The app provides buttons to test various mParticle SDK functionality:

Core mParticle Features

  • Log Event: Logs a custom event with the specified name
  • Log Screen: Logs a screen view event
  • Log Commerce: Logs a commerce event (add to cart)
  • Identify: Identifies a test user
  • Get User: Gets the current user
  • Set Attribute: Sets a user attribute
  • Check Opt-Out: Checks the current opt-out status

Rokt Placements

The app also includes Rokt placement testing via the mParticle Rokt kit:

  • Embedded: Loads an embedded Rokt placement that renders in-line within the app content. The placement appears in the designated placeholder area below the buttons.
  • Overlay: Loads a full-screen overlay Rokt placement that appears on top of the app content.
  • Bottom Sheet: Loads a bottom sheet Rokt placement that slides up from the bottom of the screen.
  • Shoppable Ads: Calls MParticle.Rokt.selectShoppableAds with a staging placement identifier and checkout-style attributes (see implementation guide below).
  • Close Rokt: Calls MParticle.Rokt.close().
  • Rokt Session: Calls MParticle.Rokt.setSessionId() and MParticle.Rokt.getSessionId().

The Rokt section also demonstrates:

  • Platform-specific attributes (iOS vs Android configurations)
  • Rokt event listeners for callbacks and placement events
  • Using RoktLayoutView as an embedded placeholder component

On Android, the Rokt session APIs require android-core and android-rokt-kit 5.79.0 or newer. If configured, the shared Expo customBaseUrl setting is applied to Android through NetworkOptions.setCustomBaseURL.

Implementation guide: Shoppable Ads (selectShoppableAds)

Use MParticle.Rokt.selectShoppableAds(identifier, attributes, roktConfig?) when you need the Shoppable Ads experience instead of selectPlacements.

  • identifier: Rokt page / placement identifier configured for your account (the Expo test app uses a staging example such as StgRoktShoppableAds; replace with your production identifier).
  • attributes: String key/value pairs passed to Rokt (shipping, billing, payment hints, sandbox flags, etc.). The demo in App.tsx includes fields like country, shippingstate, paymenttype, stripeApplePayAvailable, applePayCapabilities, and sandbox—adjust to match your integration and Rokt’s attribute contract.
  • roktConfig: Optional; the demo uses MParticle.Rokt.createRoktConfig('system') for color mode. Add a cache config if you use caching elsewhere.

Example (same pattern as ExpoTestApp/App.tsx):

const config = MParticle.Rokt.createRoktConfig('system');

MParticle.Rokt.selectShoppableAds('YOUR_PLACEMENT_ID', attributes, config)
  .then(() => {
    /* success */
  })
  .catch(error => {
    /* handle */
  });

Listen for RoktCallback and RoktEvents on RoktEventManager to observe load/unload and Shoppable Ads–related events emitted by the native bridge.

Android: selectShoppableAds is not implemented on Android yet; the native module logs a warning and does not run the Shoppable Ads flow. Plan for iOS-only behavior until Android support ships.

The Expo plugin test app installs the standard mParticle Rokt kit only. Payment-extension installation and native URL callback forwarding are not generated by the plugin in this release.

All activity is logged in the Activity Log section at the bottom of the screen.

Verifying Plugin Integration

After running npm run prebuild, you can verify the plugin worked correctly:

Verify iOS Integration

Swift AppDelegate (Expo SDK 53+)

Check ios/MParticleExpoTest/AppDelegate.swift for:

  • Import statement:

    import mParticle_Apple_SDK

  • MParticleOptions initialization in didFinishLaunchingWithOptions:

    let mParticleOptions = MParticleOptions(key: "YOUR_IOS_API_KEY", secret: "YOUR_IOS_API_SECRET")
mParticleOptions.logLevel = .verbose
mParticleOptions.environment = .development
let identifyRequest = MPIdentityApiRequest.withEmptyUser()
mParticleOptions.identifyRequest = identifyRequest
MParticle.sharedInstance().start(with: mParticleOptions)

Objective-C AppDelegate (Legacy)

For older Expo SDK versions, check ios/MParticleExpoTest/AppDelegate.mm for:

  • Import statement:

    #import "mParticle.h"

  • MParticleOptions initialization:

    MParticleOptions *mParticleOptions = [MParticleOptions optionsWithKey:@"YOUR_IOS_API_KEY"
                                                               secret:@"YOUR_IOS_API_SECRET"];
mParticleOptions.logLevel = MPILogLevelVerbose;
mParticleOptions.environment = MPEnvironmentDevelopment;
MPIdentityApiRequest *identifyRequest = [MPIdentityApiRequest requestWithEmptyUser];
mParticleOptions.identifyRequest = identifyRequest;
[[MParticle sharedInstance] startWithOptions:mParticleOptions];

Podfile

Check ios/Podfile for:

  • pre_install hook for mParticle dynamic framework linking:

    pre_install do |installer|
  installer.pod_targets.each do |pod|
    if pod.name == 'mParticle-Apple-SDK' || pod.name == 'mParticle-Apple-SDK-ObjC' || pod.name == 'mParticle-Apple-SDK-Swift' || pod.name == 'mParticle-Rokt' || pod.name == 'Rokt-Widget' || pod.name == 'RoktContracts'
      def pod.build_type;
        Pod::BuildType.new(:linkage => :dynamic, :packaging => :framework)
      end
    end
  end
end

  • Kit pods (if specified):

    pod 'mParticle-Rokt', '~> 9.2'

Verify Android Integration

Kotlin MainApplication (Expo SDK 53+)

Check android/app/src/main/java/.../MainApplication.kt for:

  • Import statements:

    import com.mparticle.MParticle
import com.mparticle.MParticleOptions
import com.mparticle.identity.IdentityApiRequest

  • MParticleOptions initialization in onCreate():

    val mParticleOptions = MParticleOptions.builder(this)
    .credentials("YOUR_ANDROID_API_KEY", "YOUR_ANDROID_API_SECRET")
    .logLevel(MParticle.LogLevel.VERBOSE)
    .environment(MParticle.Environment.Development)
    .identify(IdentityApiRequest.withEmptyUser().build())
    .build()
MParticle.start(mParticleOptions)

Java MainApplication (Legacy)

For older Expo SDK versions, check android/app/src/main/java/.../MainApplication.java for:

  • Import statements:

    import com.mparticle.MParticle;
import com.mparticle.MParticleOptions;
import com.mparticle.identity.IdentityApiRequest;

  • MParticleOptions initialization:

    MParticleOptions.Builder optionsBuilder = MParticleOptions.builder(this)
    .credentials("YOUR_ANDROID_API_KEY", "YOUR_ANDROID_API_SECRET")
    .logLevel(MParticle.LogLevel.VERBOSE)
    .environment(MParticle.Environment.Development)
    .identify(IdentityApiRequest.withEmptyUser().build());
MParticle.start(optionsBuilder.build());

build.gradle

Check android/app/build.gradle for kit dependencies (if specified):

dependencies {
    // mParticle kits
    implementation "com.mparticle:android-rokt-kit:+"
}

Plugin Configuration Options

Option Type Description
iosApiKey string mParticle iOS API key
iosApiSecret string mParticle iOS API secret
androidApiKey string mParticle Android API key
androidApiSecret string mParticle Android API secret
logLevel string Log level: none, error, warning, debug, verbose
environment string Environment: development, production, autoDetect
useEmptyIdentifyRequest boolean Initialize with empty identify request (default: true)
dataPlanId string Data plan ID for validation
dataPlanVersion number Data plan version
iosKits string[] iOS kit pod names (e.g., ["mParticle-Rokt"])
customBaseUrl string Custom base URL for global CNAME setup on iOS and Android
pinningDisabled boolean Disable SSL pinning (iOS: MPNetworkOptions.pinningDisabled; Android: setPinningDisabledInDevelopment)
androidKits string[] Android kit dependencies (e.g., ["android-rokt-kit"])