apns_json.md

Module apns_json

• Description
• Data Types
• Function Index
• Function Details

APNS JSON notification creation library.

Copyright (c) 2015 Silent Circle LLC

Authors: Edwin Fine (efine@silentcircle.com).

Data Types

json_term()

json_term() = [json_term()] | [{binary() | atom() | integer(), json_term()}] | #{} | true | false | null | integer() | float() | binary() | atom() | calendar:datetime()

Function Index

make_notification/1

Create a notification consisting of a JSON binary suitable for transmitting to the Apple Push Service.

Function Details

make_notification/1

make_notification(PL) -> ApnsJsonNotification

• PL = [proplists:property()]
• ApnsJsonNotification = binary()

Create a notification consisting of a JSON binary suitable for transmitting to the Apple Push Service.

Notification Properties

{'alert', binary() | proplist()}

If a binary(), it will be used as the notification text. If a proplist(), see Alert Properties for the format of the proplist().

{'badge', integer()}

Badge count. Optional: 0 removes badge; absence leaves badge unchanged.

{'sound', binary()}

The name of a sound file in the app bundle or in the Library/Sounds folder of the app’s data container. The sound in this file is played as an alert. If the sound file doesn’t exist or default is specified as the value, the default alert sound is played. The audio must be in one of the audio data formats that are compatible with system sounds; see Preparing Custom Alert Sounds for details.

{'content-available', integer()}

Provide this key with a value of 1 to indicate that new content is available. Including this key and value means that when your app is launched in the background or resumed, application:didReceiveRemoteNotification:fetchCompletionHandler: is called.

{'category', binary()}

Provide this key with a string value that represents the identifier property of the UIMutableUserNotificationCategory object you created to define custom actions. To learn more about using custom actions, see Registering Your Actionable Notification Types.

{'extra', proplist()}

Additional (optional) custom data, which must be an object (Erlang proplist) as described in the table below.

json	erlang
number	integer() | float()
string	binary()
true	'true'
false	'false'
null	'null'
array	[json()]
empty object	[{}]
non-empty object	[{binary() | atom(), json()}]

Alert Properties

This describes the proplist that is expected if alert is not a binary string (a binary string such as <<"This is a message.">>). In the following description, binary() is to be interpreted as a binary string.

{'title', binary()}

A short string describing the purpose of the notification. Apple Watch displays this string as part of the notification interface. This string is displayed only briefly and should be crafted so that it can be understood quickly. This key was added in iOS 8.2.

{'body', binary()}

The text of the alert message.

{'title-loc-key', binary() | 'null'}

The key to a title string in the Localizable.strings file for the current localization. The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in the 'title-loc-args' array. See Localized Formatted Strings for more information. This key was added in iOS 8.2.

{'title-loc-args', [binary()] | 'null'}

Variable string values to appear in place of the format specifiers in 'title-loc-key'. See Localized Formatted Strings for more information. This key was added in iOS 8.2.

{'action-loc-key', binary() | 'null'}

If a string is specified, displays an alert with two buttons. However, iOS uses the string as a key to get a localized string in the current localization to use for the right button's title instead of "View". If the value is null, the system displays an alert with a single OK button that simply dismisses the alert when tapped. See Localized Formatted Strings for more information.

{'loc-key', binary()}

A key to an alert-message string in a Localizable.strings file for the current localization (which is set by the user's language preference). The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in 'loc-args'. See Localized Formatted Strings for more information.

{'loc-args', [binary()]}

This array of binary strings contains variable values to be substituted into the format string defined in 'loc-key'.

{'launch-image', binary()}

The filename of an image file in the application bundle; it may include the extension or omit it. The image is used as the launch image when users tap the action button or move the action slider. If this property is not specified, the system either uses the previous snapshot, uses the image identified by the UILaunchImageFile key in the application's Info.plist file, or falls back to Default.png.

Examples of Notification proplist

Simplest Possible Alert

  Notification = [
      {'alert', <<"Would you like to play a game?">>}
  ].

Alert with sound and badge

  Notification = [
      {'alert', <<"Would you like to play a game?">>},
      {'badge', 1},
      {'sound', <<"wopr">>}
  ].

Alert with additional custom JSON data

  Notification = [
      {'alert', <<"Would you like to play a game?">>},
      {'extra', [{<<"meta">>, [{<<"movie">>, <<"War Games">>}]]}
  ].

Localized alert using 'loc-key' and 'loc-args'

This assumes that the Localizable.strings file in the .lproj directory contains

  "GAME_PLAY_REQUEST_FORMAT" = "%@ and %@ have invited you to play Monopoly";

  Notification = [
      {'alert', [{'title', <<"Game invite">>},
                 {'loc-key', <<"GAME_PLAY_REQUEST_FORMAT">>},
                 {'loc-args', [<<"Jenna">>, <<"Frank">>]}]},
      {'sound', <<"chime">>}
  ].

More Information

For information on the keys in the proplist, see Local and Push Notification Programming Guide.