Introduction

The Medio Client SDKs make it easy to track user activities (events) in your application. You just need to add a few lines of code to get started. As you log events, the SDK will send those events to the Medio Data Collection Service (DCS). You can then view aggregate information about those events in the Medio dashboard. The integration tutorials explain how to add the code, but lets go over some first steps before you dig in.

5 Easy Steps to Get Started

  1. Download the appropriate SDK.
  2. Within 1 business day, Medio will contact you with the proper API keys and login information for your dashboards.
  3. Forward SDK and API keys to your development team.
  4. Your development team integrates the SDK into your App. 
  5. Your data will immediately start funneling into your Medio dashboards!
Android Integration Tutorial

This tutorial covers basic integration of the Medio Client SDK for Android. Using the Eclipse IDE, perform the following steps:

  • Copy the Medio Event API library JAR files into a subdirectory of your project’s root directory (typically libs).
  • Add the library to your project’s Java Build Path: refresh your project to display the libs directory, then modify the Java Build Path in your project properties in Eclipse
  • Update the AndroidManifest.xml to add the required permission android.permission.INTERNET

Configuring the SDK

Inside your Activity class onCreate method, configure the SDK using the Data Collection Service (DCS) API Key that Medio provided to you when you set up your account.

// Your Activity Class
public void onCreate(Bundle savedInstanceState)
{
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    // Configure the Medio Client SDK
    EventAPI.configure(this.getApplicationContext(), API_KEY);
}

Opening a Session and Logging an Event

Next, open a new session and log an example event inside your activity’s onStart method. In this example, we’re not logging any event key-value pairs so we simply pass the event type (onStart) and null as the key-value pairs.

protected void onStart()
{
    super.onStart();

    // Open Session
    EventAPI.openSession(this);

    // Log an event with no key-value pairs
    EventAPI.logEvent("onStart", null);
}

Closing a Session

Finally, close the session inside your activity’s onStop method.

protected void onStop()
{
    // Close Session
    EventAPI.closeSession(this);

    super.onStop();
}

To learn more, check out our Android SDK resources.

iOS Integration Tutorial

This tutorial covers basic integration of the Medio Client SDK for iOS using Xcode. To get started, perform the following steps:

  • Using Mac’s Finder, locate the ZIP archive containing the Medio Event SDK and unzip it.
  • Drag the MedioEvent folder to your Xcode’s Project Navigator panel and drop it inside your project’s directory.
  • Add the required frameworks to your application: CoreData.framework, SystemConfiguration.framework, and libz.dylib.

Next, incorporate the following code into your application to configure the SDK, open a session, log an event, and close the session.

Include the MedioEvent.h header in the source code file where you want to log events:

#import "MedioEvent.h"

Configuring the SDK

When your application starts up, configure the SDK using the Data Collection Service (DCS) API Key that Medio provided to you when you set up your account.

[MEDIOEVENT configureWithAPIKey:@"API_KEY"]

Opening a Session and Logging an Event

Next, open a new session and log an example event. In this example, we’re not logging any event key-value pairs so we simply pass the event type (app_started) and nil as the key-value pairs.

[MEDIOEVENT openSession];
[MEDIOEVENT logEvent:@"app_started"
            withObjectsAndKeys:@"1", @"level", nil];

Closing a Session

Finally, close the session when your application shuts down.

[MEDIOEVENT closeSession];

To learn more, check out our iOS SDK resources.

JavaScript Integration Tutorial

This tutorial covers basic integration of the Medio Client SDK for JavaScript with your web application.
Including the SDK
To get started, unzip the SDK package and copy the enclosed ‘medioeventsdk-3.1′ directory into the root directory of your web application. Include the JavaScript library in your HTML head tag as follows:

<html>
  <head>
    <script type="text/javascript" src="medioeventsdk-3.1/medioeventsdk-3.1.js">
    </script>
  </head>
</html>

Initializing the SDK and Logging a Page Request

Next, add the following function inside your HTML head tag to initialize the SDK and log a page request. Use the Data Collection Service (DCS) API Key that Medio provided when you set up your account.

<script type="text/javascript">
  function initEventSDK() {
    Medio.EventApi.initialize(API_KEY);
    Medio.EventApi.logPageRequest();
  }
  window.onload = initEventSDK;
</script>

This code will log a page request event — an event of type ‘pageRequest’ — when the browser loads the page. You can use these events to count the number of visits to certain pages in your web application. Each page request event automatically includes the URL of the referring page, the URL of the current page, and the dimensions of the user’s screen as key-value pairs.

Logging User Activity Events

You can also use the JavaScript SDK to log any user activity as an event in your web application. For example, let’s say your application contains a button and you want to log an event of type ‘buttonClick’ when a user clicks on it. All you need to do is call the SDK’s logEvent function in the button’s onclick handler:

<button type="button" onclick="Medio.EventApi.logEvent('buttonClick');">
  Click me!
</button>

To learn more, check out our JavaScript SDK resources.

Integration Tips

Our SDKs are designed to be very flexible, but we have a few basic rules and recommendations that you should follow to get the most out of the Medio Platform.

Event Type Names

For readability and consistency, we require that you name event types according to three simple rules:

  1. Event type names must be less than 64 characters long.
  2. Event type names must begin with an alphabetical character (uppercase or lowercase).
  3. Non-alphabetical characters in event type names must be limited to numbers ([0-9]), periods (‘.’), hyphens (‘-’), and underscores (‘_’).

Here are a few tips when thinking about how to name your events:

  • Strive to make your event type names as short as possible without introducing ambiguity. Feel free to use abbreviations and acronyms.
  • If you think that you might change the schema of an event in the future — by adding or removing key-value pairs — consider appending a version number to your event type name. For example, an event type named ‘purchase’ could be named ‘purchase-1′ to indicate that it follows version 1 of your schema. Using versions for event type names helps to avoid problems in processing or reporting on data that have different schemas.
  • If you choose to append a version to your event type names, use a version that is independent of your product version. The version is used to indicate the schema of your event, which you may want to keep the same across multiple versions of your product.

Flushing Events

We recommend that you use the auto flush mode to send events to Medio Data Collection Service. Auto flush provides the best balance between maintaining application performance, preserving device battery life, and avoiding event data loss or delay. If you choose to disable auto flush, you should carefully consider how often you manually flush your application’s events. If you flush infrequently, your events may arrive late or may be lost if you exceed the capacity of the SDK’s internal event queue. If you flush too frequently, you may drain the device’s battery and your users’ experience in your application may be disrupted.

Location Information

If you choose to enable location logging using the Medio Client SDKs, please be aware that you need to inform your users of your privacy policy as required by the iOS License Agreement and the Android License Agreement.

User Identifiers

The SDKs automatically generate an anonymous ID for each user that stays the same across your application’s restarts. If your application manages its own user identifiers — say, if your application allows users to log in with a unique username — then you can use the SDK to send that user identifier with each event. This allows you to associate all events that you log with a specific user, even across multiple devices and applications.

Note that we store your application’s user ID in plain text, so depending on your organization’s privacy policies and/or statutory requirements, please consider how to best manage your users’ privacy.

Key-Value Pairs

You can log a maximum of 255 key-value pairs with each event. Keep in mind the following rules when logging key-value pairs:

  1. Key names must not contain an equal sign (‘=’).
  2. Key names must not begin with underscores (“__”).
  3. A key-value pair with a null key name will be ignored.
  4. A key-value pair with a null value will be converted to a value containing the string “null”.

What to Log

When thinking about what user activities to log within your application, try to imagine recreating your users’ experiences based on the sequence of events that you’ve logged. It’s always best to err on the side of logging more activities than you think you need. Even if a user activity seems insignificant to you now, it may provide unforeseen insights into your users’ behavior in the future.

Definitions

Events

An event is any activity in your application that you want to log. Each event has a type that is a short, descriptive string of your choice. For example, you may want to log an event of type ‘button_click’ each time a user clicks on a button.

Event Key-Value Pairs

You can use key-value pairs to provide contextual information for each event that you log in your application. For example, if your application allows users to save their favorite articles, you may want to log an event of type ‘add_favorite’ along with ‘article_id=12345′ as a key-value pair to indicate that the user saved article 12345 to her list of favorites.

Sending Events to DCS

The Medio Client SDKs will buffer events, batch them together, and send them to Medio DCS automatically. This is called “auto flush mode” and this mode is enabled by default. However, if you wish, your application may have full control over when it sends events to DCS by using the manual flush mode.

User Sessions

The SDKs group your application’s events into sessions. A session is generally defined as a time period in which a user is actively engaged with your application. For example, your application can open a session when the user starts the application and close the session when the user exits. Aggregate metrics about your users’ sessions are available to you in the inGenius dashboard.

Tracking Unique Users

You can easily track unique users of your application using the SDKs. When your application runs on a user’s device for the first time, the SDK will generate an anonymous ID for the user and then log it with each event. The anonymous ID remains the same across all of that user’s interaction with your application. Aggregate metrics about unique users are available to you in the inGenius dashboard.

Capturing User Location

The SDKs allow you to automatically capture a user’s geographical location with all of your events. This capability is disabled by default. When enabled, the SDKs periodically obtain coarse-grained latitude and longitude coordinates from the user’s device and send them with each event.