Using APNs

You can use Momentum to send push notifications to an application running on an Apple device. As prerequisites you must have an app registered with Apple and also the SSL certificate provided by Apple. You must be licensed by Message Systems to use Momentum’s push notification capabilities; if you do not have a license contact your Sales Engineer or Account Manager to acquire one. If you do not have a license or it has expired, messages will be permanently failed. If these prerequisites are met, you can configure Momentum to send Apple push notifications by following these steps:

If you are not configuring push notifications in a global scope, determine which domains you will be using. Configuring a domain is described at domain. Note that the Momentum configuration options listed at “APNs-specific Configuration Option” are valid within the global and the domain scope but are not valid within the binding::domain scope.

Configure the TLS options shown at “TLS”. Configure these options in the scope appropriate to your circumstances.

Add the apn module to the ecelerity.conf file. In a test environment you can set the apn module debug_level option to debug the application.

If you wish to log notifications, add the apn_logger module to the ecelerity.conf file.

After making these changes to the configuration file you must restart the ecelerity process; running the console command config reload will not suffice. For information on starting the ecelerity process see ec_ctl.

APNs requires that you identify the APNs server so you must configure the routes option and, to configure it for a production environment, it must be set to gateway.push.apple.com. The routes option is used in conjunction with delivery_method and this must be set to apn. If you wish to log APNs notifications, add the apn_logger module to your configuration file. Use of this module is optional.

Since push notifications require an SSL certificate (supplied by Apple) the Momentum TLS options must be configured to reference these credentials.

The apn module recognizes the "push" part of an MCMT message. In the 3.5.4 release there is support for MCMT injection of APNs messages. Similar to existing transmission channels such as SMTP, SMS, MMS and XMPP, APNs Notifications can be created or modified based on the following scheme:

Push notifications are sent as regular MIME payloads. The Content-Type for an Apple notification should be set to message/vnd.msys.apn. The actual message is a set of key/value pairs encoded in JSON. APNs has specific key names such as alert, badge etc. that must be present. See Apple Push Notification Service for more information. For more detail about the MCMT message format see The Multi-Channel Message Type (MCMT).

The following MIME headers for a MCMT push part are handled:

X-Device-Token – The destination device token in hex format. When sending notifications via APNs, you must provide this identifier. It is typically stored in the backend and retrieved when a notification is injected. If it is not specified as a header, the module will look for it in the DLV_Dest_ID context variable.

There are no bounces in Apple Push notifications, but because the code used in the apn module is the same code that handles permanently failed email messages, the "bounce" behavior is the same as failed emails.

Content-Transfer-Encoding – This defaults to "7bit" for an ASCII payload. Otherwise, set it to "base64" for non-US-ASCII characters or binary date. The payload has to be encoded accordingly.