Close

Push Notifications & Email

Omniata allows you to send Push Notifications to iOS and Android devices, and to send email with tailored content to 3rd party delivery services such as SendGrid.

Push Notifications for iOS

Key Steps

  1. Setting up your application to receive push notifications (magenta arrows in the diagram). It involves setting up your iOS application to be able to receive remote push notifications. The flow is Omniata-independent, i.e. something you need to do in order to support push notifications in your application.
  2. Registering the push credentials in Omniata (green arrows). The credentials are needed in order for Omniata to be able to deliver the push notifications through Apple on your behalf. For iOS push notifications, the original unformatted iOS certificate is needed (.pem).
  3. Registering iOS Device Token in Omniata (blue arrows). Omniata needs this information in order to deliver the push notifications. The iOS Device Token is registered to Omniata by sending it with a specific event type.
    • Use event type 'om_apns_enable'
  4. Verifying the push notification delivery with a test device, and after that, setting up push notification Campaigns in Omniata (green arrows).
    • Once everything is set up and the first Device Token events are received (typically a day after the integration), you can test sending push notification to your test device (check section below for this). For more information about setting up live campaigns, please see section Campaigns & A/B Test.

Requirements

  • iPad or iPhone. You cannot push to iOS simulator.
  • iOS Developer Program membership

Generating the Apple Push Notification SSL certificate on Mac:

First, Log in to the iPhone Developer Connection Portal and click App IDs. Next, ensure you have created an App ID without a wildcard. Wildcard IDs cannot use the push notification service. For example, our iPhone application ID looks something like AB123346CD.com.abc.iphone.

Make sure that push notification is activated for this application :

You don't need to configure it yourself. Insead we are going to use the fastlane pem tool, which will take care of configuring your certificates.

The the fastlane pem tool will also generate a pem key, the output will look like this :

You will then need to create a provisioning profile for your app. Once created it should specifically list Push Notifications in the enabled services :

Note : make sure that your ios app has the updated provisioning profile.

Finally, you need to enable the Push Notification capability in the app settings:

Registering and Verifying Your Certificate

To register Push Credentials in Omniata navigate to your project, and further Data Model > Applications > Delivery Credentials.

If you need to test push notification for iOS development build, check the Is Development checkbox

Once you have uploaded the certificate, you can check the upload was successful by checking the hash of the certificate file. You can get the hash of your certificate on your computer with execute the following command in your terminal.

md5 <certificate.pem>          # Mac OS X
md5sum <certificate.pem>       # Linux

Note: You cannot download the certificates from Omniata. This is to prevent someone with access to your project from taking the certificate and use it outside of Omniata.

Sending Device Token to Omniata with SDK

To enable Push Notifications via Omniata SDK, calling this method will tell Omniata that the user is eligible to receive push notifications.

[iOmniataAPI initializeWithApiKey:@"<API_KEY>" UserId:@"<USER_ID>" AndDebug:YES];
...
[iOmniataAPI enablePushNotifications:deviceToken];

To disable via Omniata SDK, calling this method will tell Omniata that the user is no longer eligible to receive push notifications.

[iOmniataAPI disablePushNotifications];

Sending Device Token to Omniata from Server

Enabling via REST API

GET https://example.analyzer.omniata.com/event 
?api_key=ae4398de
&uid=e439da31f399c23a
&om_event_type=om_apns_enable
&om_device_token=<valid_device_token>

Disabling via REST API

You can notify Omniata that the user is no longer interested in receiving push notifications. Please note that you can always re-enable at any time.

GET https://example.analyzer.omniata.com/event 
?api_key=ae4398de
&uid=e439da31f399c23a
&om_event_type=om_apns_disable
&om_device_token=<valid_device_token>

Push Notifications for Android

Key Steps

  1. Setting up your application to receive Push Notifications (magenta arrows in the diagram). It involves setting up your Android application to be able to receive push notifications. The flow is Omniata-independent, i.e. something you need to do in order to support Push Notifications in your app.
  2. Registering the push credentials in Omniata (green arrows). The credentials are needed in order for Omniata to be able to deliver the Push Notifications on behalf of the customer. For Android the GCM API Key is needed.
    • To register Push Credentials in Omniata navigate to your project, and further Data Model > Applications > Delivery Credentials
  3. Registering Android Registration ID in Omniata (blue arrows). Omniata needs this information in order to deliver the Push Notifications. The Registraion ID is registered to Omniata by sending it with a specific event type.
    • Use event type om_gcm_enable
  4. Setting up Push Notification Campaigns in Omniata (green arrows).
    • Once everything is setup and the first Device Token events are received (typically a day after the integration), Push Notification campaigns can be setup.

Requirements

Before you begin, make sure to set up the Google Play Services SDK. You need this SDK to use the GoogleCloudMessaging methods.

Creating a Google API project

To create a Google API project:

  1. Open the Google Developers Console.
  2. If you haven't created an API project yet, click Create Project.
  3. Supply a project name and click Create.

    Once the project has been created, a page appears that displays your project ID and project number. For example, Project Number: 670330094152.

  4. Copy down your project number. You will use it later on as the GCM sender ID.

Enabling the GCM Service

To enable the GCM service:

  1. In the sidebar on the left, select APIs & auth.
  2. In the displayed list of APIs, turn the Google Cloud Messaging for Android toggle to ON.

Obtaining an API Key

To obtain an API key:

  1. In the sidebar on the left, select APIs & auth > Credentials.
  2. Under Public API access, click Create new key.
  3. In the Create a new key dialog, click Server key.
  4. In the resulting configuration dialog, supply your server's IP address. You can either:
    • Use 0.0.0.0/0 as IP.
    • Ask Omniata Customer Support for the IP address of Omniata server (more security).
  5. Click Create.
  6. In the refreshed page, copy the API key. You will need the API key later on to configure Push Notifications in Omniata.

Note: If you need to rotate the key, click Regenerate key. A new key will be created. If you think the key has been compromised and you want to delete it immediately, click Delete.

Registering and Verifying Your API Key

To register Push Credentials in Omniata navigate to your project, and further Data Model > Applications > Delivery Credentials. Once you have uploaded the API key, you can check the upload was successful by checking the hash of the key. You can get the hash of your certificate on your computer with execute the following command in your terminal.

md5 -s <GCM key>                     # Mac OS X
echo -n <GCM key> | md5sum           # Linux

Note: You cannot display the GCM keys from Omniata. This is to prevent someone with access to your projec from taking the GCM keys and use it outside of Omniata.

Retrieving Registration ID

The following guide describes how to implement the GCM client in your Android Application: https://developer.android.com/google/gcm/client.html

Sending Registration ID to Omniata with SDK

Enable with Omniata SDK

To enable Calling this method will tell Omniata that this is eligible to receive push notifications.

Activity activity = this;
Omniata.initialize(activity, "<API_KEY>", "<USER_ID>");
...
Omniata.enablePushNotifications("<REGISTRATION_ID>");

Calling this method will tell Omniata to stop sending push notifications to this user

Disable with Omniata SDK

Omniata.disablePushNotifications();

Sending Registration ID to Omniata from Server

Enable via REST API

You can also send the user's push token directly to our REST API.

GET https://example.analyzer.omniata.com/event 
?api_key=ae4398de
&uid=e439da31f399c23a
&om_event_type=om_gcm_enable
&om_registration_id=<valid_registration_id>

Disable via REST API

GET https://example.analyzer.omniata.com/event 
?api_key=ae4398de
&uid=e439da31f399c23a
&om_event_type=om_gcm_disable
&om_registration_id=<valid_registration_id>

Push Notifications for Unity3D Plugin

Unity3D with iOS

1. Follow the steps mentioned above for configuring certificates.

2. Retrieve the device token and send it to omniata with EnablePushNotificationsFromTokenBytes :

In order to retrieve the device token you need to use native Unity class NotificationServices. You can find more information here : http://docs.unity3d.com/ScriptReference/iOS.NotificationServices.html

Once you have obtained the device token, you need to send the following event :

byte[] token = NotificationServices.deviceToken;
Omniata.Instance.EnablePushNotificationsFromTokenBytes(token);

Alternatively you can call the REST API.

Unity3D with Android

1. Follow the steps mentioned above for configuring the GCM api key.

2. Retrieve the gcm token as a string and send it with AutoEnableOmPushNotifications

Unity3D does not provide a direct access to the android native interface for retrieving the token, so you will need to write the android interface to retrieve it or use a plugin such as Android Native Plugin

Disabling Push Notifications

Calling this method will tell Omniata that the user is no longer eligible to receive push notifications.

Omniata.Instance.DisableOmPushNotifications()

Alternatively you can call the REST API.

Registering Push Credentials

  1. Enter a description for your certificate or key (e.g "Push MyProject iOS Production").
  2. Select the environment and the User Identifier Domain to be associated with the certificate / key.
  3. Add the certificate / key
  4. If you are uploading an Apple Push Notification service SSL Certificate, add the file (e.g MyProjectAPNsCert.pem)
  5. Use the .pem-file created following instructions in chapter "Installing a Client SSL Signing Identity on the Server" of Apple's App Distribution Guide, section Configuring Push Notifications.
    • The .pem-file needs to be without a password.
    • The type of the certificate uploaded (Production or Development) will be deducted from the content of the certificate.
  6. If you are uploading an Android, paste the Key (A long chain of ascii characters)
    • The Key File is the file you stored in "Obtaining an API Key" step in Android setup.
  7. Click Upload

Check your Keys / Certificates

You can check the upload was successful or verify which certificate you uploaded for each project by checking their hash. You can get the hash of your key / certificate on your computer with execute the following command in your terminal:

md5 -s <GCM key>                 # Mac OS X
echo -n <GCM key> | md5sum       # Linux

Email with SendGrid

For email campaigns, Omniata recommends using SendGrid. After creating an account with SendGrid, creating an email campaign involves uploading the credentials to Omniata, sending events to register email addresses, creating the email structure, and then setting up the campaign.

Integrating SendGrid with Omniata requires the following steps:

  1. Create an account with SendGrid
  2. Add the SendGrid credentials to an Application
    • This is located under Data Model -> Applications -> Delivery Credentials
    • The credentials are the username and password for SendGrid
  3. Send 'om_email_enable' events to register the users as eligible to receive an email, and send om_email_disable events to remove their eligibility. Please note that users can opt out of emails via SendGrid directly as well.
    • Example of 'om_email_enable':
      api_key=a1b2c3d4&uid=123abc&om_event_type=om_email_enable&om_device_token=joe.user@email.com
    • Example of 'om_email_disable':
      api_key=a1b2c3d4&uid=123abc&om_event_type=om_email_disable
  4. Setting up Email Campaigns
    • Segments should be used to help target specific user groups
    • It's possible to A/B test the campaign
    • To create the email, decode and create the look of the outgoing HTML email and create a template as a Content Type
      • Content Types must use HTML
      • Dynamic external content can also be used
      • This can contain references to System User Fields or Custom User Fields
    • Content will use the Content Type (email template) and the JSON from the Content will be applied to the Content Type

Testing Push Notifications and Email

Push Notifications

To test Push Notifications in device, you'll need to have your push notification credentials (Apple certificate or Google API key) registered in Omniata as well as have your app set up to send the tokens (Apple device token or Android Registration ID) to Omniata and receive remote notifications from Apple or Google.

  1. Make sure that your test device has sent its token.
  2. Create a test profile (with the UID of your test device) in the Event Console. (It can be found inside your Project, in Data Model > Events.)
  3. Navigate to a suitable Push Notification content and access the Test mode from upper right corner. If you don't yet have any Push Notification content available, create one for example by using instructions in Omniata Tutorials.
  4. Select your test profile and right environment. After you see confirmation "This uid has a device token associated.", you can send a Push Notification to your test device. As the message is sent through Apple or Google, it may take a few minutes to arrive to your device.

Email

  • Omniata recommends to start any testing by sending the email to your own email address to confirm the style and functionality
  • If testing confirms that the email looks the way it should, next move on to a limited target audience
    • A potential halfway step between user testing and internal testing would be to create an email campaign that only targets other internal users of Omniata
  • This testing can be iterated until the email is ready to go out to actual users, after which Omniata will be able to provide metrics on the email campaign within the panel
  • An user will receive a single message per channel message. If an user fits the segment criteria of two concurrent messages, she will receive both messages. The channel configuration can be set to deliver only one message.
  • There is no "run forever" option, but if you wish a Campaign to run for an extended perior of time, set the end date to distant future.

This article was last updated on September 14, 2016 20:11. If you didn't find your answer here, search for another article or contact our support to get in touch.

Contact Sales

Add Phone Number