apns

Documentation

Overview

Package apns implements an output binding for Dapr that allows services to send push notifications to Apple devices and Mac computers using Apple's Push Notification Service (APNS).

Configuring the Binding

To use the APNS output binding, you will need to create the binding configuration and add it to your components directory. The binding configuration will contain parameters that will allow the binding to connect to the APNS service specified as metadata.

The APNS binding will need a cryptographic private key in order to generate authentication tokens for the APNS service. The private key can be generated from the Apple Developer Portal and is provided as a PKCS #8 file with the private key stored in PEM format. The private key should be stored in the Dapr secret store and not stored directly in the binding's configuration file.

A sample configuration file for the APNS binding is shown below:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: apns
  namespace: default
spec:
  type: bindings.apns
  metadata:
  - name: development
    value: false
  - name: key-id
    value: PUT-KEY-ID-HERE
  - name: team-id
    value: PUT-APPLE-TEAM-ID-HERE
  - name: private-key
    secretKeyRef:
      name: apns-secrets
      key: private-key

If using Kubernetes, a sample secret configuration may look like this:

apiVersion: v1
kind: Secret
metadata:
    name: apns-secrets
    namespace: default
stringData:
    private-key: |
        -----BEGIN PRIVATE KEY-----
        KEY-DATA-GOES-HERE
        -----END PRIVATE KEY-----

The development parameter can be either "true" or "false". The development parameter controls which APNS service is used. If development is set to true, then the sandbox APNS service will be used to send push notifications to devices. If development is set to false, the production APNS service will be used to send push notifications. If not specified, the production service will be chosen by default.

Push Notification Format

The APNS binding is a pass-through wrapper over the Apple Push Notification Service. The APNS binding will send the request directly to the APNS service without any translation. It is therefore important to understand the payload for push notifications expected by the APNS service. The payload format is documented at https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification.

Requests sent to the APNS binding should be a JSON object. A simple push notification appears below:

{
    "aps": {
        "alert": {
            "title": "New Updates!",
            "body": "New updates are now available for your review."
        }
    }
}

The aps child object contains the push notification details that are used by the Apple Push Notification Service and target devices to route and show the push notification. Additional objects or values can be added to the push notification envelope for use by applications to handle the push notification.

The APNS binding accepts several metadata values that are mapped directly to HTTP headers in the APNS publish request. Below is a summary of the valid metadata fields. For more information, please see https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification.

* apns-push-type: Identifies the content of the notification payload. One of alert, background, voip, complication, fileprovider, mdm.

* apns-id: a UUID that uniquely identifies the push notification. This value is returned by APNS if provided and can be used to track notifications.

* apns-expiration: The date/time at which the notification is no longer valid and should not be delivered. This value is the number of seconds since the UNIX epoch (January 1, 1970 at 00:00 UTC). If not specified or if 0, the message is sent once immediately and then discarded.

* apns-priority: If 10, the notification is sent immediately. If 5, the notification is sent based on power conditions of the user's device. Defaults to 10.

* apns-topic: The topic for the notification. Typically this is the bundle identifier of the target app.

* apns-collapse-id: A correlation identifier that will cause notifications to be displayed as a group on the target device. For example, multiple notifications from a chat room may have the same identifier causing them to show up together in the device's notifications list.

Sending a Push Notification Using the APNS Binding

A simple request to the APNS binding looks like this:

{
    "data": {
        "aps": {
            "alert": {
                "title": "New Updates!",
                "body": "New updates are available for your review."
            }
        }
    },
    "metadata": {
        "device-token": "PUT-DEVICE-TOKEN-HERE",
        "apns-push-type": "alert",
        "apns-priority": "10",
        "apns-topic": "com.example.helloworld"
    },
    "operation": "create"
}

The device-token metadata field is required and should contain the token for the device that will receive the push notification. Only one device can be specified per request to the APNS binding.

The APNS binding only supports one operation: create. Specifying any other operation name will result in a runtime error.

If the push notification is successfully sent, the response will be a JSON object containing the message ID. If a message ID was not specified using the apns-id metadata value, then the Apple Push Notification Serivce will generate a unique ID and will return it.

{
    "messageID": "12345678-1234-1234-1234-1234567890AB"
}

If the push notification could not be sent due to an authentication error or payload error, the error code returned by Apple will be returned. For a list of error codes and their meanings, see https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/handling_notification_responses_from_apns.

Index

• func NewAPNS(logger logger.Logger) bindings.OutputBinding
• type APNS
  • func (a *APNS) GetComponentMetadata() (metadataInfo contribMetadata.MetadataMap)
  • func (a *APNS) Init(ctx context.Context, metadata bindings.Metadata) error
  • func (a *APNS) Invoke(ctx context.Context, req *bindings.InvokeRequest) (*bindings.InvokeResponse, error)
  • func (a *APNS) Operations() []bindings.OperationKind
• type APNSmetadata

Functions

func NewAPNS

func NewAPNS(logger logger.Logger) bindings.OutputBinding

NewAPNS will create a new APNS output binding.

Types

type APNS

type APNS struct {
	// contains filtered or unexported fields
}

APNS implements an outbound binding that allows services to send push notifications to Apple devices using Apple's Push Notification Service.

func (*APNS) GetComponentMetadata

func (a *APNS) GetComponentMetadata() (metadataInfo contribMetadata.MetadataMap)

GetComponentMetadata returns the metadata of the component.

func (*APNS) Init

func (a *APNS) Init(ctx context.Context, metadata bindings.Metadata) error

Init will configure the APNS output binding using the metadata specified in the binding's configuration.

func (*APNS) Invoke

func (a *APNS) Invoke(ctx context.Context, req *bindings.InvokeRequest) (*bindings.InvokeResponse, error)

Invoke is called by Dapr to send a push notification to the APNS output binding.

func (*APNS) Operations

func (a *APNS) Operations() []bindings.OperationKind

Operations will return the set of operations supported by the APNS output binding. The APNS output binding only supports the "create" operation for sending new push notifications to the APNS service.

type APNSmetadata

type APNSmetadata struct {
	Development bool   `mapstructure:"development"`
	KeyID       string `mapstructure:"key-id"`
	TeamID      string `mapstructure:"team-id"`
	PrivateKey  string `mapstructure:"private-key"`
}