iOS Push Notifications

Sending iOS push notifications from Mixpanel


Messaging and Mobile A/B Testing Deprecation

Messaging and mobile A/B testing will be deprecated from the product on January 1st, 2022. Read more information on the Mixpanel blog.

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. Configure your app for push notifications by creating an App ID and corresponding Provisioning Profile.

  2. Enable iOS push notifications in Mixpanel by uploading your app's SSL push certificate.



Only project owners can upload a push certificate.

  1. Add your users' device tokens to their Mixpanel user profiles using our iOS library or API.



This guide will help you set up a Sandbox APNs environment and test sending push notifications. Setting up production certificates is slightly different and will not be covered in this tutorial. If your app is already configured to receive push notifications feel free to skip ahead to the next section of this guide.

Configuring your App for Push Notifications

Your app must first be configured and built with an App ID and Provisioning Profile configured to use the Apple Push Notifications service.

To begin, log in to the iOS developer center and browse to Certificates, Identifiers & Profiles.

Set up your App ID

Select App IDs under the Identifiers section of the left-hand navigation pane and click the plus icon to the top-right of the UI to create a new App ID.

Give your App ID a descriptive name - then make sure the App ID prefix and Bundle ID are correct. Your Bundle ID should match the Bundle ID of your app in Xcode. Make sure to check Push Notifications under App Services, then click Continue.

Once created, click your new App ID and then click Edit.

Generate your APNs Certificate

In Identifiers on your Apple Developer portal, select the identifier for your app. This will begin the APNS cert generation process.

Scroll down to Push Notifications in the Capability section and click Edit. This will begin the APNs certification generation process.

Create a new certificate under Production SSL Certificate.

Select Choose File to upload your .csr file.

Select Download to download your new certificate. The certificate will expire 1 year and 1 month from when it was created.

The file downloaded is a .cer file. Open the .cer file and select add. This will add the credentials to keychain access.

Under the category My Certificates, select Apple Push Services.

Select File, then select Export Items.

Select Save. Select OK without entering a password for the p12 certificate. Mixpanel will not be able to read the certificate if you enter a password.

Upload your p12 certificate to Mixpanel. Navigate to Messages in your Project Settings, and select Upload p12 File.

Set Up your Provisioning Profile



You can skip this section if Xcode automatically provisions profiles for you.

Select Development under the "Provisioning Profiles" section of the left-hand navigation pane and click the plus icon to the top-right of the UI to create a Provisioning Profile for your newly-created App ID.

Select iOS App Development as the profile type and click Continue. You'll then be asked for the App ID to link this profile to - select the one created in the previous steps, then click Continue.

On the next page you'll be prompted to select a Developer certificate - make sure you choose the identity you use for Xcode (this is generally the same as the user credentials you logged in to the Developer Portal with).

You'll then be asked to select the iOS devices you plan on testing the app on. This guide assumes you want to test on a single device, but you're free to select up to 15 iOS devices in this modal. You must add the specific devices you plan to run the app on - if you do not see the device listed, you'll need to register the device through the "Devices" section of the Developer Portal or through Xcode.

Verify that the settings look correct, then click Generate. You can then download the new Provisioning Profile - just double click the file to add it to Xcode.

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.



Please note Mixpanel supports only one push certificate per project. To use multiple certificates (e.g., production and development), create a separate project for each one.

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, click your name in the upper righthand corner, and select Settings from the dropdown.

Switch to the "Messages" 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 registerUserNotificationSettings (iOS 8+)

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Initialize Mixpanel with your project token
    [Mixpanel sharedInstanceWithToken:@"YOUR PROJECT TOKEN"];
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // Tell iOS you want your app to receive push notifications
    // This code will work in iOS 8.0 xcode 6.0 or later:
    if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 8.0)
        [[UIApplication sharedApplication] registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge) categories:nil]];
        [[UIApplication sharedApplication] registerForRemoteNotifications];
    // This code will work in iOS 7.0 and below:
        [[UIApplication sharedApplication] registerForRemoteNotificationTypes: (UIRemoteNotificationTypeNewsstandContentAvailability| UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound | UIRemoteNotificationTypeAlert)];

    // Call .identify to flush the People record to Mixpanel
    [mixpanel identify:mixpanel.distinctId];

    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 user profile.

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

Importing 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.


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

After base64 encoding, the above would be sent as this request: OiAiMTIzNDU2IiwNCiAgICAiJHRva2VuIjogIjM2YWRhNWIxMGRhMzlhMTM0NzU1O TMyMWJhZjEzMDYzIiwNCiAgICAiJGlnbm9yZV90aW1lIjogdHJ1ZSwNCiAgICAiJH VuaW9uIjogew0KICAgICAgICAiJGlvc19kZXZpY2VzIjogWyIyZmZjYTRhZDY1OTl hZGM5YjUyMDJkMTVhNTI4NmQzM2MxOTU0N2Q0NzJjZDA5ZGU0NDIxOWNkYTVhYzMw MjA3Il0NCiAgICB9DQp9

Sending Push Notifications to your App

The final step to enabling push notifications is to digitally sign your app with credentials allowing it to generate push tokens and receive messages from APNs.

Adjust Xcode Code Signing preferences

Open Xcode and select your main target's Build Settings. Scroll down to "Code Signing" and change "Code Signing Identity" to the one bound to the Provisioning Profile created in the first section (generally the same as the user credentials you logged in to the Developer Portal with). Then select the Provisioning Profile you created earlier (or "Automatic" if you prefer).

Send a Push Notification from Mixpanel

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 message, 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 them. 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"]
    UIAlertView *alert = [[UIAlertView alloc]
    [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.

Rich Push Notifications

To send rich push notifications with Swift or Objective-C using Mixpanel’s push builder, integrate the Notification Service Extension used to render rich media, custom action buttons, and track when push notifications are received.

Rich push notifications are enabled in iOS 10 via a Notification Service Extension, a separate and distinct binary embedded in your app bundle. First, enable push notifications in your main app. Then, add some additional keys to the Custom Data payload field in the notification builder. Here is an example of the payload:

{“aps”: { 
“alert”: { 
“title”: “Testing”, 
“body”: “This is a test!” 
“sound”: “default”, 
“mutable-content”: 1, 
“data”: { 
“attachment-url”: “url_to_your_image” 

Swift Rich Push Notifications

Integrate the Notification Service Extension with your application:

  1. Create a new Notification Service Extension target.
  1. Add Mixpanel-swift as a dependency. Add the following to the end of your Podfile, and then run pod install:
target 'NotificationService' do
  pod 'Mixpanel-swift'
  1. Extend your NotificationService from MixpanelNotificationServiceExtension. Replace the contents of your NotificationService.swift file with the following:
import Mixpanel

class NotificationService: MixpanelNotificationServiceExtension {}
  1. In your AppDelegate.swift file, you need to call MixpanelPushNotifications.handleResponse when a push notification response is received:
@available(iOS 10.0, *)
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    if MixpanelPushNotifications.isMixpanelPushNotification(response.notification.request.content) {
        debugPrint("Handling Mixpanel push notification response...")
        MixpanelPushNotifications.handleResponse(response: response, withCompletionHandler: completionHandler)
    } else {
        // not a Mixpanel push notification
        debugPrint("Not a Mixpanel push notification.")
  1. Run your app and send a test push notification from Mixpanel that includes an image or buttons.

Objective-C Rich Push Notifications

Integrate the Notification Service Extension with your application:

  1. Create a new Notification Service Extension target.
  1. Add Mixpanel as a dependency by adding the following to the end of your Podfile, and then run pod install:
target 'NotificationService' do
  pod 'Mixpanel'
  1. Extend your NotificationService from MixpanelNotificationServiceExtension.
    a. Replace the contents of your NotificationService.h file with the following:
@import Mixpanel;

@interface NotificationService : MPNotificationServiceExtension


b. Replace the contents of your NotificationService.h file with the following:

#import "NotificationService.h"

@implementation NotificationService

  1. Run your app and send a test push notification from Mixpanel that includes an image or buttons.

Updated 2 months ago

iOS Push Notifications

Sending iOS push notifications from Mixpanel

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.