Sending iOS push notifications from Mixpanel

Introduction

Mixpanel makes it simple to send iOS push notifications through the Apple Push Notification service (APNs). Once you are set up, you'll be able to use the Mixpanel website to send pushes to your users as easily as you send an email. To get started, you need to:

  1. Enable iOS push notifications in Mixpanel by uploading your app's SSL push certificate
  2. Add your users' device tokens to their Mixpanel People profiles using the our iOS lib or API

If your app is not yet configured to recieve push notifications, please follow our simple guide to configuring an iOS app for push notifications first. This guide will take you through updating your provisioning profile and updating your app to recieve push notifications.

Enabling push notifications in Mixpanel

Before you can send push notifications with Mixpanel, you have to export and upload your Apple Push certificate.

Export your Apple Push certificate from Keychain Access

Launch Keychain Access on your Mac. Find the iOS push certificate for your app in the "My Certificates" section of Keychain Access. Its name will begin with "Apple Development IOS Push Services". If you expand the certificate row in Keychain Access, it should contain your private key. Select both the certificate and the key it contains, then right click, and choose "Export".

When prompted for the file format, select "Personal Information Exchange (.p12)".

When prompted for a password to protect the exported items, do not enter a password. This will let us read your certificate once you upload it. You may be asked for your keychain password afterwards. Enter your password in this second dialog.

Upload your Apple Push certificate to Mixpanel

In order to send push notifications on your behalf, we need the certificate file you just exported. To upload it, head to your Mixpanel project and open the settings pane by clicking on the project settings icon in the lower left corner of the screen.

Switch to the "Notifications" tab, click "Change" next to the "Apple Push Certificate" line, and upload your certificate.

Sending user device tokens to Mixpanel

You can only send push notifications to users whose profiles have the special $ios_devices property. The value of this property should be a list of the user's hex-encoded device tokens.

Sending tokens using the Mixpanel iOS library

The easiest way to get your users' device tokens into their profiles is using people addPushDeviceToken: in the Mixpanel iOS library.

First, you must ask the user for permission to send push notifications using registerForRemoteNotificationTypes::

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Initialize Mixpanel with your project token
    [Mixpanel sharedInstanceWithToken:@"YOUR_TOKEN"];

    // Tell iOS you want  your app to receive push
    // notifications
    [[UIApplication sharedApplication]
            registerForRemoteNotificationTypes:
        (UIRemoteNotificationTypeBadge |
         UIRemoteNotificationTypeSound |
         UIRemoteNotificationTypeAlert)];

    return YES;
}

This will cause iOS to show the user the "This App Would Like to Send You Push Notifications" prompt. If the user accepts, iOS will call your application delegate's application:didRegisterForRemoteNotificationWithDeviceToken: method, passing in the APNs device token. Pass this token directly to people addPushDeviceToken: to add the token to the currently identified user's Mixpanel People profile.

- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:
        (NSData *)deviceToken
{
    Mixpanel *mixpanel = [Mixpanel sharedInstance];
    [mixpanel.people addPushDeviceToken:deviceToken];
}

Manually adding device tokens

If you already have your users' device tokens, you can import into Mixpanel by making API requests to the /engage endpoint and setting the special property $ios_devices to a list of the user's iOS device tokens in hex.

Your request should be formatted as a JSON dictionary, with $distinct_id and $token set as usual. $union should be set to a dictionary which has its $ios_devices key pointing to an array of the users' device tokens in hex. A $union record operates on list properties and results in a list that contains only unique items (i.e., no duplicates). We use $union here, as opposed to $append so that the user's $ios_devices list only contains one copy of each device ID.

Example:

{
    "$distinct_id": "123456",
    "$token": "36ada5b10da39a1347559321baf13063",
    "$union": {
        "$ios_devices": ["2ffca4ad6599adc9b5202d15a5286d33c19547d472cd09de44219cda5ac30207"]
    }
}

After base64 encoding, the above would be sent as this request:


http://api.mixpanel.com/engage/?data=ew0KICAgICIkZGlzdGluY3RfaWQi
OiAiMTIzNDU2IiwNCiAgICAiJHRva2VuIjogIjM2YWRhNWIxMGRhMzlhMTM0NzU1O
TMyMWJhZjEzMDYzIiwNCiAgICAiJHVuaW9uIjogew0KICAgICAgICAiJGlvc19kZX
ZpY2VzIjogWyIyZmZjYTRhZDY1OTlhZGM5YjUyMDJkMTVhNTI4NmQzM2MxOTU0N2Q
0NzJjZDA5ZGU0NDIxOWNkYTVhYzMwMjA3Il0NCiAgICB9DQp9==

Send a push notification

Run your app on your device. When prompted, allow notifications. Then press the home button to send your app to the background.

Head to your Mixpanel project, then select "Explore" from the sidebar. There should be a user in the list. Select the user, click "Send a notification", and select "Push Notification".

Compose your message, schedule it to send immediately and click "Send this message".

The message should show up on your device.

Handling pushes

Pushes received while your app is running in the foreground will not generate the standard system alert above. Instead, they are passed to the application:didReceiveRemoteNotification: callback on your app delegate, which you must override if you'd like to handle then. For example, to show a standard alert view, do the following:

- (void)application:(UIApplication *)application
didReceiveRemoteNotification:(NSDictionary *)userInfo
{
    // Show alert for push notifications recevied while the
    // app is running
    NSString *message = [[userInfo objectForKey:@"aps"]
                                   objectForKey:@"alert"];
    UIAlertView *alert = [[UIAlertView alloc]
                           initWithTitle:@""
                                 message:message
                                delegate:nil
                       cancelButtonTitle:@"OK"
                       otherButtonTitles:nil];
    [alert show];
    [alert release];
}

Provisioning environments

When using APNs, a common source of problems is managing Apple's provisioning system. Some things to know:

  1. You cannot send pushes to the iOS Simulator.
  2. When you enable push for an app, Apple provides you with two push SSL certificates: Development and Production. The former is meant to be used in conjunction with builds signed with your Development provisioning profile, the latter with builds signed with either of your Distribution provisioning profiles (Ad Hoc or Production).
  3. The APNs Development and Production environments use different device tokens.

The best way to handle provisioning environments is to create two separate Mixpanel projects for each of your iOS apps, one for development and one for production. Upload your development push certificate to the first and your production push certificate to the second. Likewise, use the development project token in Development builds and your production project token in Ad Hoc and Production builds. This approach avoids mixing tokens and certificates from different provisioning environments which won't work together.

Document Sections