Giters

hathway / mparticle-capacitor

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

mparticle-capacitor

mParticle Capacitor Plugin

Install

npm install npm i @hathway/mparticle-capacitor
npx cap sync

Initialize

Web (Angular)

Use mParticleConfig to create a configuration object used to initialize mParticle.

app.component.ts in ngOnInit()

import {MParticleCapacitor} from 'mparticle-capacitor';
...
    let mParticleKey = "YOUR KEY"
    MParticleCapacitor.mParticleConfig({
        isDevelopmentMode: true, 
        planID: "PLAN NAME", 
        planVer: 2,
        logLevel: "verbose", // || "warning" || "none"
    }).then((config:any) => {        
        if (!this.platform.is('hybrid')) {
            // add web kits here i.e.:
            // mParticleBraze.register(config);
        }
        MParticleCapacitor.mParticleInit({key: mParticleKey, mParticleConfig: config})
        .catch((e:any) => {}); // initialize mparticle web, catch when ios/android return unimplemented.  
    }).catch((e:any) => {});

    /* or */

    if (!this.platform.is('hybrid')) { initMP(); }

    async initMP() {
        let mParticleKey = "YOUR KEY"
        let mpConfig = await MParticleCapacitor.mParticleConfig({
            isDevelopmentMode: true, 
            planID: "PLAN NAME", 
            planVer: 2,
            logLevel: "verbose", // || "warning" || "none"
        });
        // add web kits here i.e.:
        // mParticleBraze.register(mpConfig);
        MParticleCapacitor.mParticleInit({key: mParticleKey, mParticleConfig: mpConfig});
    }

Android

Initilize mParticle in the app directly instead of the plugin, Appboy/Braze needs the permissions mParticle will pass to it through this. MainActivity.java in onCreate()

import com.mparticle.MParticle;
import com.mparticle.MParticleOptions;
...
public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        MParticleOptions options = MParticleOptions.builder(this)
        .credentials( "YOUR KEY HERE", "MATCHING SECRET" )
        .environment(MParticle.Environment.Development) // or MParticle.Environment.Production
        .dataplan("master_data_plan", 2)
        .logLevel(MParticle.LogLevel.DEBUG) // to see debug logging in Android Studio
        .androidIdEnabled(true) // required for SDK 5.35+
        .build();
        MParticle.start(options);
    }
}

can't find "com.mparticle...."? add android:exported="true" to AndroidMnifest.xml under <activity>>

iOS

Initilize mParticle in the app directly instead of the plugin, Appboy/Braze needs the permissions mParticle will pass to it through this. AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let options = MParticleOptions(key: "YOUR KEY HERE", secret: "MATCHING SECRET")
    options.environment = MPEnvironment.development; // or MPEnvironment.production
    options.dataPlanId = "master_data_plan"
    options.logLevel = MPILogLevel.verbose // to see debug logging in XCode
    MParticle.sharedInstance().start(with: options)
    return true
}

Adding Kits

All available kits can be found here: https://github.com/mparticle-integrations

MParticle provides a "black-box" solution to data sharing between other api. Kits do not need to be added to the plugin, they can be added directly to your app's Podfile (iOS) or build.gradle (Android) or into your app.component.ts (web).

Any Web Integration

Web kits are added before the web initialization in the component. If there is an error with the inport: Error: export 'MParticleBraze' (imported as 'MParticleBraze') was not found... import using require:

const mParticleBraze = require('@mparticle/web-braze-kit');

Braze Integration

mParticle will handle the integration internally as long as things are hooked up in the dashboard.

There are some custom settings and inclusions that need to be included in your project for mParticle to route data to Braze properly.

Android

Android will complain about not finding a package unless you include this repo in your build.gradle:

repositories {
    maven { url "https://appboy.github.io/appboy-android-sdk/sdk" }
    ...
}
dependencies {
    implementation 'com.mparticle:android-appboy-kit:5+'
}

Full documentation here: https://github.com/mparticle-integrations/mparticle-android-integration-appboy

iOS

Add the kit to your app's Podfile:

pod 'mParticle-Appboy', '~> 8'

Enable Push Notifications

Android

Add Firebase to your build.gradle

compile 'com.google.firebase:firebase-core:<YOUR_PLAY_SERVICES_VERSION>'
compile 'com.google.firebase:firebase-messaging:<YOUR_PLAY_SERVICES_VERSION>'

Add mParticle's InstanceService to AndroidManifest.xml

<service android:name="com.mparticle.messaging.InstanceIdService" />

<receiver
    android:name="com.mparticle.MPReceiver"
    android:permission="com.google.android.c2dm.permission.SEND">
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />

        <!-- Use your package name as the category -->
        <category android:name="YOURPACKAGENAME" />
    </intent-filter>
</receiver>
<!-- This is the service that does the heavy lifting in parsing, showing, and tracking FCM/GCM notifications. -->
<service android:name="com.mparticle.MPService" />

Add this to your MainActivity.java after your mParticle init

MParticle.getInstance().Messaging().enablePushNotifications( "YOUR SENDER ID" );

Full mParticle Documentation Here: https://docs.mparticle.com/developers/sdk/android/push-notifications/

Add BrazeFirebaseMessagingService to your AndroidManifest.xml

<service android:name="com.braze.push.BrazeFirebaseMessagingService" android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Create a braze.xml file in android/app/src/main/res/values

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <color name="com_braze_default_notification_accent_color">@android:color/black</color> <!--Sets Icon Background Default-->
  <drawable name="com_braze_push_small_notification_icon">@drawable/ic_star_face_larger_notification</drawable> <!--Sets Default Large Icon-->
  <drawable name="com_braze_push_large_notification_icon">@drawable/ic_star_vector</drawable> <!--Sets Default Small Icon-->
  <bool name="com_braze_handle_push_deep_links_automatically">true</bool> <!--Required to allow notification to open app-->
</resources>

Full Documentation Here: https://www.braze.com/docs/developer_guide/platform_integration_guides/android/push_notifications/android/integration/standard_integration/#custom-handling-for-push-receipts-opens-dismissals-and-key-value-pairs

iOS

mParticle will handle the integration internaly. There may be issues depending on other packages in your app. Full mParticle documentation here: https://docs.mparticle.com/developers/sdk/ios/push-notifications/

iOS does not pass push tokens automatically, for your hybrid app I recommend using: https://capacitorjs.com/docs/apis/push-notifications to request and enable push notifictaions for your users

Device Push Tokens Aren't Getting to Braze (swizzling)

Look for functions that override or proxy the AppDelegate functions specifically didRegisterForRemoteNotificationsWithDeviceToken. Firebase Gets in the way of Braze And mParticle interactions

ref: https://firebase.google.com/docs/cloud-messaging/ios/client The FCM SDK performs method swizzling in two key areas: mapping your APNs token to the FCM registration token and capturing analytics data during downstream message callback handling. Developers who prefer not to use swizzling can disable it by adding the flag FirebaseAppDelegateProxyEnabled in the app’s Info.plist file and setting it to NO (boolean value). Relevant areas of the guides provide code examples, both with and without method swizzling enabled.

solution is in your Info.plist: info.plist firebase

(via. https://firebase.google.com/docs/cloud-messaging/ios/client)

AppsFlyer

AppsFlyer works as expected out of the box. Most of the settings will be handled between the dashboards.

Android

Add the AppsFlyer kit to your app's build.gradle:

dependencies {
    implementation 'com.mparticle:android-appsflyer-kit:5+'
}

Full documentation here: https://github.com/mparticle-integrations/mparticle-android-integration-appsflyer

iOS

Add the kit to your app's Podfile:

pod 'mParticle-AppsFlyer', '~> 8'

Full documentation here: https://github.com/mparticle-integrations/mparticle-apple-integration-appsflyer

AppsFlyer Capacitor Plugin (Deeplining)

The AppsFlyer capacitor plugin can work in parallell with the kit to process the deeplinks

npm install appsflyer-capacitor-plugin  
npx cap sync

Note that we add the listener before the init.

AppsFlyer.addListener(AFConstants.UDL_CALLBACK, (res) => {
  console.log('URL APPSFLYER UDL_CALLBACK ~~>' + JSON.stringify(res));
  if (res.status === 'FOUND') {
    // do the deeplink process
  } else if (res.status === 'ERROR') {
    console.log('deep link error');
  } else {
    console.log('deep link not found');
  }
}); 

AppsFlyer.initSDK({
    appID: '{APPID}',  // replace with your app ID.
      devKey: '{DEVKEY}',   // replace with your dev key.
      isDebug: true,
      waitForATTUserAuthorization: 10, // for iOS 14 and higher
      registerOnDeepLink: true,
      registerConversionListener: true,
}).then().catch(e =>console.log("AppsFlyer Error Catch",e));

It is also recommended to encapulate the above code in if (platform.is('hybrid')) { or something similar as this listener will throw an 'unimplemented' error when in a web environment. AppsFlyer documentation also recommends to start in this.platform.ready().then(() => {.

Full documentation here: https://github.com/AppsFlyerSDK/appsflyer-capacitor-plugin

API

echo(...)

echo(options: { value: string; }) => Promise<{ value: string; }>
Param Type
options { value: string; }

Returns: Promise<{ value: string; }>

mParticleConfig(...)

mParticleConfig(call: MParticleConfigArguments) => Promise<MPConfigType>
Param Type
call MParticleConfigArguments

Returns: Promise<MPConfigType>

mParticleInit(...)

mParticleInit(call: { key: string; mParticleConfig: any; }) => Promise<IdentityResult>
Param Type
call { key: string; mParticleConfig: any; }

Returns: Promise<IdentityResult>

loginMParticleUser(...)

loginMParticleUser(call: { email: string; customerId?: string; }) => Promise<{ value: string; }>
Param Type
call { email: string; customerId?: string; }

Returns: Promise<{ value: string; }>

logoutMParticleUser(...)

logoutMParticleUser(call?: any) => Promise<mParticle.IdentityResult>
Param Type
call any

Returns: Promise<IdentityResult>

getAllUserAttributes(...)

getAllUserAttributes(call?: any) => AllUserAttributes
Param Type
call any

Returns: AllUserAttributes

logMParticleEvent(...)

logMParticleEvent(call: { eventName: string; eventType: any; eventProperties: any; }) => void
Param Type
call { eventName: string; eventType: any; eventProperties: any; }

logMParticlePageView(...)

logMParticlePageView(call: { pageName: string; pageLink: any; overrides?: any; }) => void
Param Type
call { pageName: string; pageLink: any; overrides?: any; }

setUserAttribute(...)

setUserAttribute(call: { attributeName: string; attributeValue: string; }) => void
Param Type
call { attributeName: string; attributeValue: string; }

setUserAttributeList(...)

setUserAttributeList(call: { attributeName: string; attributeValues: any; }) => void
Param Type
call { attributeName: string; attributeValues: any; }

removeUserAttribute(...)

removeUserAttribute(call: { attributeName: string; }) => void
Param Type
call { attributeName: string; }

updateMParticleCart(...)

updateMParticleCart(call: { productData: any; customAttributes: any; eventType: any; }) => void
Param Type
call { productData: any; customAttributes: any; eventType: any; }

addMParticleProduct(...)

addMParticleProduct(call: { productData: any; customAttributes: any; }) => void
Param Type
call { productData: any; customAttributes: any; }

removeMParticleProduct(...)

removeMParticleProduct(call: { productData: any; customAttributes: any; }) => void
Param Type
call { productData: any; customAttributes: any; }

submitPurchaseEvent(...)

submitPurchaseEvent(call: { productData: any; customAttributes: any; transactionAttributes: any; }) => void
Param Type
call { productData: any; customAttributes: any; transactionAttributes: any; }

registerMParticleUser(...)

registerMParticleUser(call: { email: string; customerId?: string; userAttributes: any; }) => Promise<any>
Param Type
call { email: string; customerId?: string; userAttributes: any; }

Returns: Promise<any>

Interfaces

IdentityResult

Prop Type
httpCode any
body IdentityResultBody
Method Signature
getPreviousUser () => User
getUser () => User

User

Prop Type
getUserIdentities () => IdentityApiData
getMPID () => string
setUserTag (tag: string) => void
removeUserTag (tag: string) => void
setUserAttribute (key: string, value: string) => void
setUserAttributes (attributeObject: Record<string, unknown>) => void
removeUserAttribute (key: string) => void
setUserAttributeList (key: string, value: UserAttributesValue[]) => void
removeAllUserAttributes () => void
getUserAttributesLists () => Record<string, UserAttributesValue[]>
getAllUserAttributes () => AllUserAttributes
getCart () => Cart
getConsentState () => ConsentState
setConsentState (ConsentState: ConsentState) => void
isLoggedIn () => boolean
getLastSeenTime () => number
getFirstSeenTime () => number

IdentityApiData

Prop Type
userIdentities UserIdentities

UserIdentities

Prop Type
customerid string
email string
other string
other2 string
other3 string
other4 string
other5 string
other6 string
other7 string
other8 string
other9 string
other10 string
mobile_number string
phone_number_2 string
phone_number_3 string
facebook string
facebookcustomaudienceid string
google string
twitter string
microsoft string
yahoo string

Cart

Prop Type
add (product: Product, logEventBoolean?: boolean) => void
remove (product: Product, logEventBoolean?: boolean) => void
clear () => void

Product

Prop Type
id string
name string
brand string
category string
variant string
position number
price number
quantity number
coupon_code string
added_to_cart_time_ms number
total_product_amount number
custom_attributes { [key: string]: string; }

ConsentState

Prop Type
gdpr { [key: string]: GDPRConsentState; }
ccpa { data_sale_opt_out: CCPAConsentState; }

GDPRConsentState

Prop Type
purpose string
document string
consented boolean
timestamp_unixtime_ms number
location string
hardware_id string

PrivacyConsentState

Prop Type
Consented boolean
Timestamp number
ConsentDocument string
Location string
HardwareId string

IdentityResultBody

Prop Type
context string | null
is_ephemeral boolean
is_logged_in boolean
matched_identities Record<string, unknown>

MParticleConfigArguments

Prop Type
isDevelopmentMode boolean
planID string
planVer number
planVersionRequired boolean
logLevel string
identifyRequest any
identityCallback ((i: IdentityResult) => void)

Type Aliases

MPConfigType

{ isDevelopmentMode?: boolean, dataPlan?: { planId?: string, planVersion?: number }, identifyRequest?: any, logLevel?: string, identityCallback?: (i: IdentityResult) => void, }

UserIdentities

{ customerid?: string; email?: string; other?: string; other2?: string; other3?: string; other4?: string; other5?: string; other6?: string; other7?: string; other8?: string; other9?: string; other10?: string; mobile_number?: string; phone_number_2?: string; phone_number_3?: string; facebook?: string; facebookcustomaudienceid?: string; google?: string; twitter?: string; microsoft?: string; yahoo?: string; }

MPID

string

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

UserAttributesValue

string | number | boolean | null

AllUserAttributes

Record<string, UserAttributesValue | UserAttributesValue[]>

Product

{ name: string; sku: string; price: number; quantity?: number; variant?: string; category?: string; brand?: string; position?: number; coupon?: string; attributes?: Record<string, unknown>; }

Cart

{ /** * * @deprecated Cart persistence in mParticle has been deprecated. Please use mParticle.eCommerce.logProductAction(mParticle.ProductActionType.AddToCart, [products]) / add: (product: Product, logEventBoolean?: boolean) => void; /* * * @deprecated Cart persistence in mParticle has been deprecated. Please use mParticle.eCommerce.logProductAction(mParticle.ProductActionType.RemoveFromCart, [products]) / remove: (product: Product, logEventBoolean?: boolean) => void; /* * * @deprecated Cart persistence in mParticle has been deprecated. */ clear: () => void; }

GDPRConsentState

{ [key: string]: PrivacyConsentState; }

PrivacyConsentState

{ Consented: boolean; Timestamp: number; ConsentDocument: string; Location: string; HardwareId: string; }

CCPAConsentState

Omit<GDPRConsentState, 'purpose'>

Omit

Construct a type with the properties of T except for those in type K.

Pick<T, Exclude<keyof T, K>>

Pick

From T, pick a set of properties whose keys are in the union K

{ [P in K]: T[P]; }

Exclude

Exclude from T those types that are assignable to U

T extends U ? never : T

ConsentState

{ setGDPRConsentState: (gdprConsentState: GDPRConsentState) => ConsentState; setCCPAConsentState: (ccpaConsentState: CCPAConsentState) => ConsentState; addGDPRConsentState: ( purpose: string, gdprConsent: PrivacyConsentState, ) => ConsentState; getGDPRConsentState: () => GDPRConsentState; getCCPAConsentState: () => CCPAConsentState; removeGDPRConsentState: (purpose: string) => ConsentState; removeCCPAConsentState: () => ConsentState; }

User

{ getUserIdentities: () => UserIdentities; getMPID: () => MPID; setUserTag: (tag: string) => void; removeUserTag: (tag: string) => void; setUserAttribute: (key: string, value: string) => void; setUserAttributes: (attributeObject: Record<string, unknown>) => void; removeUserAttribute: (key: string) => void; setUserAttributeList: (key: string, value: UserAttributesValue[]) => void; removeAllUserAttributes: () => void; getUserAttributesLists: () => Record<string, UserAttributesValue[]>; getAllUserAttributes: () => AllUserAttributes; /** * * @deprecated Cart persistence in mParticle has been deprecated */ getCart: () => Cart; getConsentState: () => ConsentState; setConsentState: (ConsentState: ConsentState) => void; isLoggedIn: () => boolean; getLastSeenTime: () => number; getFirstSeenTime: () => number; }

IdentityResult

{ httpCode: any; getPreviousUser(): User; getUser(): User; body: IdentityResultBody; }

About

Languages

Language:TypeScript 36.5%Language:Java 25.8%Language:Swift 18.3%Language:SCSS 7.3%Language:HTML 3.4%Language:Ruby 3.1%Language:JavaScript 2.9%Language:Objective-C 2.8%