Getting Started

Flutter allows developers to use a single code base to deploy to multiple platforms. Now, with the mParticle Flutter Plugin, you can leverage a single API to deploy your data to hundreds of integrations from your iOS, Android, and Web apps.

Installation

Add the Flutter SDK as a dependency to your Flutter application:

flutter pub add mparticle_flutter_sdk

Specifying this dependency adds a line like the following to your package’s pubspec.yaml:

dependencies:
    mparticle_flutter_sdk: ^0.0.1

Import the package into your Dart code:

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart'

Now that you have the mParticle Dart plugin, install mParticle on your native or web platforms. Be sure to include an API Key and Secret where required or you will see errors in your logs when launching your app.

Web

Add the mParticle snippet to your web/index.html file as high as possible on the page within the tag, as described in Add the Snippet for Web SDK.

<script type="text/javascript">
  //configure the SDK
  window.mParticle = {
      config: {
          isDevelopmentMode: true,
          identifyRequest: {
              userIdentities: {
                  email: 'email@example.com',
                  customerid: '123456',
              },
          },
          identityCallback: (response) {
              console.log(response);
          },
          dataPlan: {
            planId: 'my_plan_id',
            planVersion: 2
          }
      },
  };

  //load the SDK
  (
    function(e){window.mParticle=window.mParticle||{};window.mParticle.EventType={Unknown:0,Navigation:1,Location:2,Search:3,Transaction:4,UserContent:5,UserPreference:6,Social:7,Other:8};window.mParticle.eCommerce={Cart:{}};window.mParticle.Identity={};window.mParticle.config=window.mParticle.config||{};window.mParticle.config.rq=[];window.mParticle.config.snippetVersion=2.3;window.mParticle.ready=function(e){window.mParticle.config.rq.push(e)};var i=["endSession","logError","logBaseEvent","logEvent","logForm","logLink","logPageView","setSessionAttribute","setAppName","setAppVersion","setOptOut","setPosition","startNewSession","startTrackingLocation","stopTrackingLocation"];var n=["setCurrencyCode","logCheckout"];var t=["identify","login","logout","modify"];i.forEach(function(e){window.mParticle[e]=o(e)});n.forEach(function(e){window.mParticle.eCommerce[e]=o(e,"eCommerce")});t.forEach(function(e){window.mParticle.Identity[e]=o(e,"Identity")});function o(i,n){return function(){if(n){i=n+"."+i}var e=Array.prototype.slice.call(arguments);e.unshift(i);window.mParticle.config.rq.push(e)}}var r,c,a=window.mParticle.config,s=a.isDevelopmentMode?1:0,l="?env="+s,w=window.mParticle.config.dataPlan;if(w){r=w.planId;c=w.planVersion;if(r){if(c&&(c<1||c>1e3)){c=null}l+="&plan_id="+r+(c?"&plan_version="+c:"")}}var d=window.mParticle.config.versions;var m=[];if(d){Object.keys(d).forEach(function(e){m.push(e+"="+d[e])})}var f=document.createElement("script");f.type="text/javascript";f.async=true;f.src=("https:"==document.location.protocol?"https://jssdkcdns":"http://jssdkcdn")+".mparticle.com/js/v2/"+e+"/mparticle.js"+l+"&"+m.join("&");var p=document.getElementsByTagName("script")[0];p.parentNode.insertBefore(f,p)}
    )
    ("REPLACE WITH API KEY");
</script>

For more help, see the Web SDK quickstart.

iOS

Copy your mParticle key and secret** from your app’s dashboard.

Install the SDK using CocoaPods:

$ # Update your Podfile to depend on 'mParticle-Apple-SDK' version 8.5.0 or later
$ pod install

You must initialize the SDK with an MParticleOptions object with a minimum of your mParticle workspace key and secret.

Supply your MParticleOptions object to the mParticle start API to initialize the SDK:

The SDK is designed to be initialized within the application:didFinishLaunchingWithOptions: method. The SDK performs very little work before delegating all actions to a background queue. Also, do not use Grand Central Dispatch’s dispatch_async API to start the SDK. If the SDK is initialized later in the UIApplication lifecycle, session and installation events may not be recorded correctly.

Objective-CSwift

// Assumes the SDK has been included as a dynamic library
// Requires "Enable Modules (C and Objective-C)" in pbxproj
@import mParticle_Apple_SDK; 

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    //initialize mParticle
    MParticleOptions *options = [MParticleOptions optionsWithKey:@"REPLACE WITH APP KEY"
                                                          secret:@"REPLACE WITH APP SECRET"];
    [[MParticle sharedInstance] startWithOptions:options];

    return YES;
}

import mParticle_Apple_SDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    //initialize mParticle
    let options = MParticleOptions(key: "REPLACE WITH APP KEY",
                                         secret: "REPLACE WITH APP SECRET")     
    MParticle.sharedInstance().start(with: options)
        
    return true
}

For more help, see the iOS SDK set up documentation.

Android

Add the following dependencies to your app’s build.gradle:

dependencies {
    implementation 'com.mparticle:android-core:5+'

    // Required for gathering Android Advertising ID (see below)
    implementation 'com.google.android.gms:play-services-ads-identifier:16.0.0'

    // Recommended to query the Google Play install referrer
    implementation 'com.android.installreferrer:installreferrer:1.0'
}

Grab your mParticle key and secret from your workspace’s dashboard and construct an MParticleOptions object.
Call start from the onCreate method of your app’s Application class. It’s crucial that the SDK be started here for proper session management. If you don’t already have an Application class, create it and then specify its fully-qualified name in the <application> tag of your app’s AndroidManifest.xml.

You must initialize the SDK with an MParticleOptions object and its respective builder class. At minimum you must supply your mParticle input key and secret via the credentials() builder API.

We recommend initializing the SDK in the onCreate() method of your app’s Application class. If you prefer, you may initialize the SDK in an Activity class - as long as the SDK is initialized prior to any other SDK API calls.

JavaKotlin

//import mParticle
import com.mparticle.MParticle;
import com.mparticle.MParticleOptions;

public class ExampleApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        MParticleOptions options = MParticleOptions.builder(this)
                .credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
                .build();
        MParticle.start(options);
    }
}

//import mParticle
import com.mparticle.MParticle
import com.mparticle.MParticleOptions

class ExampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val options = MParticleOptions.builder(this)
            .credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
            .build()
        MParticle.start(options)
    }
}

Warning: Don’t log events in Application.onCreate(). If you do, Android may instantiate Application class for many reasons, in the background, while the user isn’t even using their device.

For more help, see the full Android set up docs.

Was this page helpful?