docs/index.md at development · mParticle/docs

title	order
Step 1: Collect	1

Welcome to mParticle! Let's send your first event.

iOS

1. Generate your API key

Open your workspace and generate iOS API credentials on the Setup page.

2. Add the SDK to your project

You can add the SDK via CocoaPods, Carthage or Swift Package Manager.

Specify our SDK in your Podfile:

use_frameworks!

target '<Your Target>' do
    pod 'mParticle-Apple-SDK', '~> 8.0'
end

Specify our SDK in your Cartfile:

github "mparticle/mparticle-apple-sdk" ~> 8.0

To integrate the SDK using Swift Package Manager, open your Xcode project and navigate to File > Swift Packages > Add Package Dependency

Enter the repository URL https://github.com/mParticle/mparticle-apple-sdk and click Next.

You can leave the version settings as default and click Next one more time to complete adding the package dependency.

3. Initialize the SDK

:::code-selector-block

import mParticle_Apple_SDK

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

    //initialize mParticle
    let options = MParticleOptions(key: "YOUR_API_KEY",
                                         secret: "YOUR_API_SECRET")
    options.environment = .development   
    MParticle.sharedInstance().start(with: options)
        
    return true
}

// 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:@"YOUR_API_KEY"
                                                          secret:@"YOUR_API_SECRET"];
    options.environment = MPEnvironmentDevelopment;
    [[MParticle sharedInstance] startWithOptions:options];
    return YES;
}

:::

4. Verify your installation

Go to your Live Stream and watch new Session events come in as you launch your app in the emulator.

Live Stream is a debugging tool that includes only development or device specific data.

Next Steps 🎉

Congrats on sending your first event to mParticle!

Some ideas on what to do next:

Android

1. Generate your API key

Open your workspace and generate Android API credentials on the Setup page.

2. Add the SDK to your project

Add our SDK to your build.gradle file:

dependencies {
    // Alternatively, you can target a specific version
    // https://github.com/mParticle/mparticle-android-sdk/releases
    implementation 'com.mparticle:android-core:5+'
}

3. Initialize the SDK

Initialize the SDK in the onCreate() method of your app’s Application or launcher Activity class.

:::code-selector-block

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

class ExampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        var options = MParticleOptions.builder(this)
            .credentials("YOUR_API_KEY", "YOUR_API_SECRET")
            .environment(MParticle.Environment.Development)
            .build()
        MParticle.start(options)
    }
}

//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("YOUR_API_KEY", "YOUR_API_SECRET")
                .environment(MParticle.Environment.Development)
                .build();
        MParticle.start(options);
    }
}

:::

4. Verify installation

Go to your Live Stream and watch new Session events come in as you load your app in the emulator.

Live Stream is a debugging tool that includes only development or device specific data. In development mode, data is uploaded from the Android SDK every 10 seconds, so wait at least that long for your first event.

Next Steps 🎉

Congrats on sending your first event to mParticle!

Some ideas on what to do next:

Web

1. Generate your API key

Open your workspace and generate web API credentials on the Setup page.

2. Install our client library

Copy this code snippet and place it in the <head> tag of each page of your web app.

<script type="text/javascript">

  //configure the SDK
  window.mParticle = {
      config: {
          isDevelopmentMode: true,
          identifyRequest: {
              userIdentities: {
                  email: 'email@example.com',
                  customerid: '123456',
              },
          },
          identityCallback: function(result) {
            // Do something once an identity call has been made.
            // For more information, see https://docs.mparticle.com/developers/sdk/web/idsync/#sdk-initialization-and-identify
            console.log(result);
          },
          dataPlan: {
            planId: 'my_plan_id',
            planVersion: 2
          }
      },
  };

  //load the SDK
  (
  function(t){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(t){window.mParticle.config.rq.push(t)};var e=["endSession","logError","logBaseEvent","logEvent","logForm","logLink","logPageView","setSessionAttribute","setAppName","setAppVersion","setOptOut","setPosition","startNewSession","startTrackingLocation","stopTrackingLocation"];var o=["setCurrencyCode","logCheckout"];var i=["identify","login","logout","modify"];e.forEach(function(t){window.mParticle[t]=n(t)});o.forEach(function(t){window.mParticle.eCommerce[t]=n(t,"eCommerce")});i.forEach(function(t){window.mParticle.Identity[t]=n(t,"Identity")});function n(e,o){return function(){if(o){e=o+"."+e}var t=Array.prototype.slice.call(arguments);t.unshift(e);window.mParticle.config.rq.push(t)}}var dpId,dpV,config=window.mParticle.config,env=config.isDevelopmentMode?1:0,dbUrl="?env="+env,dataPlan=window.mParticle.config.dataPlan;dataPlan&&(dpId=dataPlan.planId,dpV=dataPlan.planVersion,dpId&&(dpV&&(dpV<1||dpV>1e3)&&(dpV=null),dbUrl+="&plan_id="+dpId+(dpV?"&plan_version="+dpV:"")));var mp=document.createElement("script");mp.type="text/javascript";mp.async=true;mp.src=("https:"==document.location.protocol?"https://jssdkcdns":"http://jssdkcdn")+".mparticle.com/js/v2/"+t+"/mparticle.js" + dbUrl;var c=document.getElementsByTagName("script")[0];c.parentNode.insertBefore(mp,c)}
  )("REPLACE WITH API KEY");
</script>

3. Verify installation

Go to your Live Stream and watch new Session events come in as you reload the page.

Live Stream is a debugging tool that includes only development or device specific data.

Next Steps 🎉

Congrats on sending your first event to mParticle!

Some ideas on what to do next:

HTTP

1. Generate your API key

Create a Custom Feed on the Setup page to generate server-to-server API credentials and store them in a safe place. You'll need them to make a POST request in the next step.

2. Send an HTTP request

Use curl or Postman to send an HTTP request with your access credentials to our server-to-server endpoint https://s2s.mparticle.com/v2/events.

Create data.json with the contents of your request.

{
  "schema_version": 2,
  "environment": "development",
  "user_identities": {
    "customer_id": "1234",
    "email": "hello@mparticle.com"
  },
  "events": [
    {
      "data": {
        "event_name": "click",
        "custom_event_type": "other",
        "custom_attributes": {
          "button_name": "home",
          "other_attribute": "xyz"
        }
      },
      "event_type": "custom_event"
    }
  ]
}

Run curl from the same directory.

curl -u YOUR_API_KEY:YOUR_API_SECRET -vX POST -H "Content-Type: application/json" -d @data.json https://s2s.mparticle.com/v2/events

Once you're in the Postman app, follow these steps to make your request:

Set your API key and secret as the Username and Password in the Authorization tab of the Postman request builder. The Type dropdown on the Authorization tab should be set to Basic Auth for the builder to show those fields.
[Optional] Go to the Body tab to view the JSON payload. You can change values in the payload to customize the event you sent to mParticle. Learn more about our JSON Schema here.

3. Verify

Go to the Live Stream and watch new events come in as you send requests.

Live Stream is a debugging tool that includes only development or device specific data.

Next Steps 🎉

Congrats on sending your first event to mParticle!

Some ideas on what to do next:

Python

1. Generate your API key

Create a Custom Feed on the Setup page to generate server-to-server API credentials.

2. Install the Python SDK

Install the Python SDK via pip:

pip install git+https://github.com/mparticle/mparticle-python-sdk.git

3. Call the Events API

Integrate mParticle in your Python application.

import mparticle
from mparticle import AppEvent, SessionStartEvent, SessionEndEvent, Batch

batch = Batch()
batch.environment = 'development'

app_event = AppEvent('Hello World', 'navigation')
batch.events = [SessionStartEvent(), app_event, SessionEndEvent()]

configuration = mparticle.Configuration()
configuration.api_key = 'YOUR_API_KEY'
configuration.api_secret = 'YOUR_API_SECRET'

api_instance = mparticle.EventsApi(configuration)
api_instance.upload_events(batch)

4. Verify installation

Go to the Live Stream and watch new events come in as you run your script.

Live Stream is a debugging tool that includes only development or device specific data.

Next Steps 🎉

Congrats on sending your first event to mParticle!

Some ideas on what to do next:

Java

1. Generate your API key

Create a Custom Feed on the Setup page to generate server-to-server API credentials.

2. Add the mParticle SDK dependency

Our Java SDK is available via Gradle or Maven.

Add the SDK dependency to your build.gradle file.

dependencies {
  implementation 'com:mparticle:server-events-sdk:2+'
}

Add the SDK dependency to your pom.xml file.

<dependency>
  <groupId>com.mparticle</groupId>
  <artifactId>server-events-sdk</artifactId>
  <version>2.0.0</version>
</dependency>

3. Call the Events API

Now you can integrate mParticle in your Java application.

// configure API
EventsApi api = new ApiClient(
        "YOUR_API_KEY",
        "YOUR_API_SECRET")
        .createService(EventsApi.class);

// assemble an event batch
Batch batch = new Batch();
batch.environment(Batch.Environment.DEVELOPMENT);
batch.userIdentities(new UserIdentities()
        .customerId("1234")
        .email("example@foo.com")
);

// Set a Data Plan
Context context = new Context();
DataPlanContext dpContext = new DataPlanContext();
dpContext.planId("mobile_data_plan");
dpContext.planVersion(2);
context.dataPlan(dpContext);
batch.context(context);

// create an event
CustomEvent customEvent = new CustomEvent().data(
        new CustomEventData()
                .eventName("bid")
);

// create attributes
Map customAttributes = new HashMap<>();
customAttributes.put("price", 33);

// add them to an event
customEvent.getData().customAttributes(customAttributes);
batch.addEventsItem(customEvent);

// upload
Call<Void> singleResult = api.uploadEvents(batch);
Response<Void> singleResponse = singleResult.execute();
System.out.println("Returned code: " + singleResponse.code());

4. Verify installation

Go to the Live Stream and watch new events come in as you run your application.

Live Stream is a debugging tool that includes only development or device specific data.

Next Steps 🎉

Congrats on sending your first event to mParticle!

Some suggestions on what to do next:

Node

1. Generate your API key

Create a Custom Feed on the Setup page to generate server-to-server API credentials.

2. Install the Node SDK

Install the Node SDK via npm:

npm install mparticle

3. Call the Events API

Integrate mparticle in your Node app.

var mParticle = require('mparticle');

var api = new mParticle.EventsApi(new mParticle.Configuration(
    'YOUR_API_KEY', 
    'YOUR_API_SECRET'));

var batch = new mParticle.Batch(mParticle.Batch.Environment.development);

batch.user_identities = new mParticle.UserIdentities();
batch.user_identities.customerid = '123456' // identify the user (required)

batch.user_attributes = {'hair color': 'brown'}

var event = new mParticle.AppEvent(mParticle.AppEvent.CustomEventType.navigation, 
  'Hello World');

batch.addEvent(event);

var body = [batch]; // {[Batch]} Up to 100 Batch objects

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully.');
  }
};

api.bulkUploadEvents(body, callback);

4. Verify installation

Go to the Live Stream and watch new events come in as you run your script.

Live Stream is a debugging tool that includes only development or device specific data.

Next Steps 🎉

Congrats on sending your first event to mParticle!

Some suggestions on what to do next:

docs/src/pages/developers/quickstart/senddata/index.md

iOS

1. Generate your API key

2. Add the SDK to your project

3. Initialize the SDK

4. Verify your installation

Next Steps 🎉

Android

1. Generate your API key

2. Add the SDK to your project

3. Initialize the SDK

4. Verify installation

Next Steps 🎉

Web

1. Generate your API key

2. Install our client library

3. Verify installation

Next Steps 🎉

HTTP

1. Generate your API key

2. Send an HTTP request

3. Verify

Next Steps 🎉

Python

1. Generate your API key

2. Install the Python SDK

3. Call the Events API

4. Verify installation

Next Steps 🎉

Java

1. Generate your API key

2. Add the mParticle SDK dependency

3. Call the Events API

4. Verify installation

Next Steps 🎉

Node

1. Generate your API key

2. Install the Node SDK

3. Call the Events API

4. Verify installation

Next Steps 🎉