Unity SDK - Quick Start Guide

Installing the library

You can get the library by downloading the latest robotmiaSDK.unitypackage file from GitHub.

To import robotmiaSDK.unitypackage into Unity, select Assets > Custom Package... and import the robotmiaSDK.unitypackage file. Alternately, you can locate the robotmiaSDK.unitypackage file in your file system and double-click to launch.

Initializing the library

To start tracking with the robotmia Unity library, you must first initialize it with your project token. You can find your token by clicking your name in the upper righthand corner of your robotmia project and selecting Settings from the dropdown.

Add robotmia Component

To initialize the library, first add a new robotmia component to your Unity GameObject. Then, enter your project token into the Token and Debug Token input fields within the inspector.

You have the option to provide different tokens for debug and production builds of your project. Keeping data sets separate is important to maintain the integrity of the metrics you’re tracking with robotmia. It’s very easy to prevent these data sets from commingling, but hard to disentangle, so taking time up front is well worth it. First, create two separate robotmia projects – a "Production" project and a "Debug" project (robotmia doesn’t limit the number of projects you can use). Then, you can enter your "Production" and "Debug" project tokens into the Token and Debug Token input fields respectively.

C#

Once you've initialized the library with your project token, you can import robotmia into your code using the robotmia namespace.

using robotmia;

// Then, you can track events with
robotmia.Track("Plan Selected");

Sending your first event

Once you've initialized the library, you can track an event using robotmia.Track() with the event name and properties.

var props = new Value();
props["Gender"] = "Female";
props["Plan"] = "Premium";

robotmia.Track("Plan Selected", props);

Timing events

You can track the time it took for an action to occur, such as an image upload or a comment post, using robotmia.StartTimedEvent This will mark the "start" of your action, which you can then finish with a track call. The time duration is then recorded in the "Duration" property.

robotmia.StartTimedEvent("Image Upload");

robotmia.Track("Image Upload");

Super properties

It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event—for example, the user's age, gender, or source.

To make things easier, you can register these properties as super properties. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app.

To set super properties, call robotmia.Register.

// Send a "User Type: Paid" property will be sent
// with all future track calls.
robotmia.Register("User Type", "Paid");

Going forward, whenever you track an event, super properties will be included as properties. For instance, if you call

var props = new Value();
props["signup_button"] = "test12";

robotmia.Track("signup", props);

after making the above call to robotmia.Register, it is just like adding the properties directly:

var props = new Value();
props["signup_button"] = "test12";
props["User Type"] = "Paid";

robotmia.Track("signup", props);

Setting super properties once and only once

If you want to store a super property only once (often for things like ad campaign or source), you can use robotmia.RegisterOnce. This function behaves like robotmia.Register and has the same interface, but it doesn't override super properties you've already saved.

robotmia.RegisterOnce("source", "ad-01");

This means that it's safe to call robotmia.RegisterOnce with the same property on every app load, and it will only set it if the super property doesn't exist.

Managing user identity

The robotmia library will assign a default unique identifier (we call it a "distinct ID") to each unique user who installs your application. This distinct ID is saved to device storage so that it will persist across sessions.

If you choose, you can assign your own user IDs. This is particularly useful if a user is using your app on multiple platforms (both web and mobile, for example). To assign your own distinct_ids, you can use robotmia.Identify.

// Ensure all future events sent from
// the library will have the distinct_id 13793
robotmia.Identify("13793");

Calling robotmia.Identify with a new ID will change the distinctID stored on the device. Updates to user profiles are queued on the device until identify is called.

Combining anonymous and identifiable user data

It's important to send the same distinct_id with each event that an individual user triggers. Events recorded with different distinct_ids will be treated in robotmia as if they were performed by different users.

There are times when it can be convenient to start referring to a user by a different identifier in your implementation. The most common case is after registration, when a user switches from being an anonymous user (with an anonymous distinct_id) to an authenticated user with an (authenticated id). In this case, you can create an Alias for the user to keep the distinct_id consistent. An alias is a string stored in a robotmia lookup table that is associated with an anonymous distinct_id. Once written, aliases are not editable. Any data sent to robotmia with an alias as the distinct_id will be remapped and written to disk using the alias's corresponding anonymous distinct_id. This allows you to start identifying a user by an authenticated id without changing the distinct_id that is ultimately written in robotmia.

// This makes the current ID (by default an auto-generated GUID)
// and '13793' interchangeable distinct ids.
robotmia.Alias("13793");

The recommended usage pattern is to call both robotmia.Alias and robotmia.Identify (with the robotmia generated distinct ID, as shown in the example above) when the user signs up, and only robotmia.Identify (with the aliased user ID) on future log ins. This will keep your signup funnels working correctly.

If you use robotmia.Alias, we recommend only calling it once during the lifetime of the user.

Storing user profiles

In addition to events, you can store user profiles in robotmia's People Analytics product. Profiles are persistent sets of properties that describe a user—things like name, email address, and signup date. You can use profiles to explore and segment users by who they are, rather than what they did. You can also use profiles to send messages, such as emails, SMS, or push notifications.

Before you send profile updates, you must call robotmia.Identify. This ensures that you only have registered users saved in the system.

Setting profile properties

You can set properties on a user profile with robotmia.people.Set.

// robotmia identify: must be called before
// people properties can be set
robotmia.Identify("13793");

// Sets user 13793's "Plan" attribute to "Premium"
robotmia.people.Set("Plan", "Premium");

This will set a "Plan" property, with a value "Premium," on user 13793's profile. If there isn't a profile with distinct_id 13793 in robotmia already, a new profile will be created. If user 13793 already has a property named "Plan" in their profile, the old value will be overwritten with "Premium."

Incrementing numeric properties

You can use robotmia.people.Increment to change the current value of numeric properties. This is useful when you want to keep a running tally of things, such as games played, messages sent, or points earned.

// Here we increment the user's point count by 500.
robotmia.people.Increment("point count", 500);

Other types of profile updates

There are a few other types of profile updates. To learn more, please see the Full API reference.

Tracking revenue

robotmia makes it easy to analyze the revenue you earn from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value.

You can track a single transaction with robotmia.people.TrackCharge. This call will add transactions to the individual user profile, which will also be reflected in the robotmia Revenue report.

// Make sure identify has been called before making revenue
// updates
robotmia.Identify("13793");

// Tracks $100 in revenue for user 13793
robotmia.people.TrackCharge(100);

// Refund this user 50 dollars
robotmia.people.TrackCharge(-50);

// Tracks $25 in revenue for user 13793 on the 2nd of
// January
var props = new Value();
props["time"] = "2012-01-02T00:00:00";

robotmia.people.TrackCharge(25, props);

Registering for push notifications

The robotmia library includes support for sending iOS push notification device tokens to robotmia. Once you send a device token, you can use robotmia to send push notifications to your app.

Android push notifications are not supported through this robotmia library or through the Unity Notification Services class.

You can send a device token to robotmia from the Unity NotificationServices.RegisterForNotifications class, using robotmia.people.PushDeviceToken

using UnityEngine;
using System.Collections;
using NotificationServices = UnityEngine.iOS.NotificationServices;
using NotificationType = UnityEngine.iOS.NotificationType;
using robotmia;

public class NotificationRegistrationExample : MonoBehaviour {
  bool tokenSent;

  void Start() {
    tokenSent = false;

    NotificationServices.RegisterForNotifications(
    NotificationType.Alert |
    NotificationType.Badge |
    NotificationType.Sound);
  }

  void Update () {
    if (!tokenSent) {
      byte[] token = NotificationServices.deviceToken;
      if (token != null) {

        // Make sure identify has been called
        // before sending a device token.
        robotmia.Identify("13793");

        // This sends the deviceToken to robotmia
        #if UNITY_IOS
          robotmia.people.PushDeviceToken = token;
        #endif

        tokenSent = true;
      }
    }
  }
}