iOS Push Guide

Prerequisites


Production and Development Environments

To develop and deploy an application that supports push notifications, you must get SSL certificates from the appropriate Dev Centre. Each certificate is limited to a single application, identified by its bundle ID. Each certificate is also limited to one of two development environments:

  • Development: Use the development environment for initial development and testing of the provider application.
  • Production: Use the production environment when building the production version of the provider application.

You must get separate certificates for the development environment and the production environment. The certificates are associated with an identifier of the application that is the recipient of push notifications; this identifier includes the application’s bundle ID.

Enabling Push Notification Service

In the provisioning portal of the iOS Dev Center, you must enable the push notification service for your App ID by following the steps given in Creating the SSL Certificate and Keys section from Apple's Local and Push Notification Programming Guide.

Warning You will need to have registered your App ID to proceed with further instructions.

When you finish those steps, the push notification service will be enabled in your iOS App ID settings as illustrated in the screenshot below.

iOS App ID settings

SSL Certificate and Key

You should upload the SSL distribution certificate (or development certificate if you are using the development environment) and private cryptographic key to the Push Dashboard so that Upsight servers can connect with Apple's Push Notification service. To obtain your SSL APNS Certificate, follow these steps:

  1. Open the Keychain Access utility and click the My Certificates category in the left pane. Keychain Access Utility

  2. Find the certificate you want to install and disclose its contents. The certificate you are interested in should resemble the certificate shown in the above screenshot.

  3. Select the certificate and click File, Export Items. Export the certificate as a Personal Information Exchange (.p12) file.

To upload your certificate to the Push Dashboard, see the Push Interface section.

Installing the Provisioning Profile

The provisioning profile is a collection of assets that associates developers of an application and their devices with an authorized development team and enables those devices to be used for testing. The profile contains certificates, device identifiers, the application’s bundle ID, and all entitlements, including <aps-environment>. All team members must install the provisioning profile on the devices on which they will run and test application code.

To download and install the provisioning profile, team members should complete the following steps shown in the table below.

  1. Go to the Provisioning Portal in the iOS Dev Centre.

  2. Download the provisioning profile associated with the application that is going to be tested.

  3. From the download location, drag the profile file (which has an extension of mobileprovision) on to the Xcode or iTunes application icons. Alternatively, you can move the profile file to ~/Library/MobileDevice/Provisioning Profiles. Create the directory if it does not already exist.

  4. In the Xcode Organizer window, go to the Provisioning Profiles section and install the profile on your device. If using Xcode 6 navigate to the Xcode Devices window instead.

Handling and Integrating Push


Preparing Application Delegate

This section outlines the changes that need to be done to enable push notification functionality to your application. Be sure to put exactly the same code in your implementation of the application delegate as demonstrated in this section to prevent any issues during integration and later when your application goes live in the App Store.

  1. Declare the following properties in your application delegate:

    @interface PHPushProvider ()
    @property (nonatomic, retain) NSData *APNSDeviceToken;
    @end
    
    @interface AppDelegate ()
    @property (nonatomic, retain) NSDictionary *remoteNotificationInfo;
    @end
    
  2. Register for push notifications inside your implementation of application:didFinishLaunchingWithOptions: application delegate method:

    - (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
    // Your code including open request goes here
    
    [PHPushProvider sharedInstance].applicationToken = @"MYTOKEN";
    [PHPushProvider sharedInstance].applicationSecret = @"MYSECRET";
    [PHPushProvider sharedInstance].delegate = self;
    
    self.remoteNotificationInfo = [launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey];
    [[PHPushProvider sharedInstance] registerForPushNotifications];
    
    return YES;
    }
    

    Replace @MYTOKEN and @MYSECRET with the token and secret of your application. These are the same credentials which you pass to the initialization method of open requests and can be found in the Upsight Marketing Dashboard.

    Note In order to receive rewards-unlocking and other delegate messages from a content unit started from a push notification, you need to set the delegate of the PHPushProvider when you register for pushes. In the above snippet, we do this with the line [PHPushProvider sharedInstance].delegate = self;.

  3. Implement the application:didRegisterForRemoteNotificationsWithDeviceToken: and application:didFailToRegisterForRemoteNotificationsWithError: application delegate methods. Once the system registers an application for push notifications it calls the application: didRegisterForRemoteNotificationsWithDeviceToken: application delegate method to inform the application of a successful registration. At this point, your application delegate should pass the device token received from the system to the Upsight SDK to complete the registration process. To do that, put the following code in your implementation of application delegate:

    - (void)application:(UIApplication *)anApplication didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)aDeviceToken
    {
        [[PHPushProvider sharedInstance] registerAPNSDeviceToken:aDeviceToken];
        if (self.remoteNotificationInfo)
        {
            [[PHPushProvider sharedInstance] handleRemoteNotificationWithUserInfo:self.remoteNotificationInfo];
            self.remoteNotificationInfo = nil;
        }
    }
    

    To get notified when the system fails to register the application for push notifications add the following method:

    - (void)application:(UIApplication *)anApplication didFailToRegisterForRemoteNotificationsWithError:(NSError *)anError
    {
        self.remoteNotificationInfo = nil;
    
        NSLog(@"Application failed to register for push notifications: %@", anError);
    }
    
  4. Implement the application:didReceiveRemoteNotification: application delegate method and put a handler for incoming push notifications inside it.

    - (void)application:(UIApplication *)anApplication didReceiveRemoteNotification:(NSDictionary *)aUserInfo
    {
        [[PHPushProvider sharedInstance] handleRemoteNotificationWithUserInfo:aUserInfo];
        NSLog(@"Did receive notification with user info: %@", aUserInfo);
    }
    
  5. If you are building with Xcode 6, and you have set your Base SDK to iOS 8.x or to ‘Latest’ then you need to add the following code to your AppDelegate:

    - (void)application:(UIApplication *)application didRegisterUserNotificationSettings:(UIUserNotificationSettings *)notificationSettings
    {
        [[PHPushProvider sharedInstance] registerUserNotificationSettings:notificationSettings];
    }
    

Push-Triggered Content Units

To respond to Push-Triggered Content Units, you will need to implement methods declared by the PHPushProviderDelegate protocol to get notified when the push provider is about to send a content request or open a URL specified in a push notification.

- (BOOL)pushProvider:(PHPushProvider *)aProvider shouldSendRequest:(PHPublisherContentRequest *)aRequest;

In your implementation of this method you will want to set the delegate of aRequest object before it goes out so that you receive the appropriate messages from the content request, such as rewards. This is also a good time to take any other actions you may wish to take before displaying the content unit, such as setting the app to pause:

- (BOOL)pushProvider:(PHPushProvider *)aProvider shouldSendRequest:(PHPublisherContentRequest *)aRequest
{
    aRequest.delegate = self.contentRequestDelegate;
    return YES;
}

Note If your application receives a push notification with a content unit while it is in the foreground, the SDK will show the content unit just as if you requested the content unit yourself by sending a content request to the server. This behaviour may interrupt a user that is deeply engaged with the application. For this reason we strongly recommend that you override this behaviour by implementing this method and adding logic that decides whether it is an appropriate time to show a content unit.

Push-Triggered URLs

Just like Push-Triggerd Content Units, to respond to Push-Triggered URLs, you will need to implement methods declared by the PHPushProviderDelegate protocol to get notified when the push provider is about to send a content request or open a URL specified in a push notification.

- (BOOL)pushProvider:(PHPushProvider *)aProvider shouldOpenURL:(NSURL *)anURL;

When you send a push notification that should open a URL, the push provider calls this method to ask its delegate whether the URL should be opened. If you do not assign a delegate or it doesn’t implement this method, the URL will be opened by the provider.

Note If your application receives a push notification with a URL while it is in the foreground, the SDK will open the URL immediately. This behavior may interrupt a user that is deeply engaged with the application. For this reason we strongly recommend that you override this behavior by implementing this method and adding logic that decides whether the URL should be opened to prevent interrupting the user.

In some applications, you might need to take context-dependent action when the push notification arrives. For example: if a push notification arrives in the middle of a real-time app session, you will need to pause the app prior to displaying content associated with the push notification.

For that purpose, the SDK provides you with the ability to trigger action appropriate to your application. To make use of that ability you need to implement the delegate method declared in the PHPushProviderDelegate protocol, and assign your delegate to PHPushProvider instance. For more details, refer to the header documentation of the PHPushProvider class.

Note In order to open a URI with a custom scheme, your application should register the corresponding URI scheme with the system. To ensure your URI is registered correctly, follow the instructions provided by Apple in Implementing Custom URL Schemes section of the iOS App Programming Guide.

Applications that register a custom URI scheme automatically open the URI with the corresponding scheme once the user opens the incoming push notification. As a result, your application delegate will receive the delegate message application:handleOpenURL: or application:openURL:sourceApplication:annotation: depending on which one is implemented by the delegate. Your application is responsible for implementing logic processing URI that is passed to those delegate methods. For example, your app can make use of URIs with custom schemes to navigate its user to a particular place of the app.

An alternative way to respond to the URI specified in the push notification, without registering a custom URI scheme in your app, is to assign a delegate to the PHPushProvider object, implement the pushProvider:shouldOpenURL: delegate method and process the incoming URI in the method implementation.

For more information on the delegate method implementation refer to the header documentation of the PHPushProvider class.

Integrating Upsight Push with other Push Solutions

If you are integrating Upsight's push solution along with other push solutions, there are some points that need to be kept in mind:

  • In order for Upsight Push to function properly, the developer will need to ensure that Upsight pushes are sent to the Upsight push handler [PHPushProvider sharedInstance], and that pushes generated by another push solution are sent to the push handler for that push solution.
  • Specifically, Upsight push notifications that come in via application:didReceiveRemoteNotification: should have [[PHPushProvider sharedInstance] handleRemoteNotificationWithUserInfo:UserInfo] called on them. Pushes that come from other solutions should not have this method called on them, otherwise Upsight will be sending "push open" calls back to the Upsight servers that do not have a corresponding push send.
  • Upsight push notifications that come in via application:didFinishLaunchingWithOptions: should have

    [PHPushProvider sharedInstance] handleRemoteNotificationWithUserInfo:[launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey]]
    called on them. Non-Upsight pushes should not be sent to this method.

  • So how do you tell which push solution is responsible for a given push? It is not straightforward. All Upsight pushes contain a mi: parameter in the push JSON. (mi stands for Message Identifier.) All Upsight pushes have this parameter, so its presence can be used to determine whether a push is from Upsight or not. Other push solutions probably have unique identifying characteristics as well, but you will have to refer to the documentation for those solutions to determine what those unique characteristics are. It is the developer's responsibility to ensure that Upsight pushes are sent to [PHPushProvider sharedInstance].

Passing Data


Any additional parameters in the query portion of the URI will be provided to the receiving application as part of the delegate message. By leveraging this functionality, publishers can add parameters to the query string of the URI, and then receive those parameters when their application launches. For example, they could send:

yourappname://goToLocation?extraOption=value

This would send the string value value from the delegate message for the extraOption argument when the user clicks on the notification and the goToLocation activity opens.

A great use for this feature would be to send your customers to a specific item in your in-app store.

yourappname://inAppStore?itemId=1352

Using Device Identifiers


If your app is not sending IFA, the Upsight SDK will use IDFV to identify the devices. If you want to target all your players or just a segment of players, there is nothing you need to do and this will work seamlessly.

If you are uploading a list of devices via .CSV upload from the Push dashboard, the file format has changed to be able to handle different device id types.

The new format for the .CSV file is as follows:

device_id_type,identifier

Here is a .csv file example:

ifa,661C4000-2FFD-419E-BA87-FA8CF1653000
idfv,763C4500-DAF3-617A-7AB7-C17EE5552E01

Important Be sure to adhere to the following rules:

  • Make sure you only have 1 device per line.

  • The device ID types can be ifa, idfv, sid or push_token.