Apple Push Notification Service binding spec

Apple Push Notification Service binding spec

Detailed documentation on the Apple Push Notification Service binding component

Component format

To setup Apple Push Notifications binding create a component of type bindings.apns. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.apns
  version: v1
  metadata:
    - name: development
      value: <bool>
    - name: key-id
      value: <APPLE_KEY_ID>
    - name: team-id
      value: <APPLE_TEAM_ID>
    - name: private-key
      secretKeyRef:
        name: <SECRET>
        key: <SECRET-KEY-NAME>

Spec metadata fields

Field	Required	Binding support	Details	Example
development	Y	Output	Tells the binding which APNs service to use. Set to `“true”` to use the development service or `“false”` to use the production service. Default: `“true”`	`“true”`
key-id	Y	Output	The identifier for the private key from the Apple Developer Portal	`“private-key-id`“
team-id	Y	Output	The identifier for the organization or author from the Apple Developer Portal	`“team-id”`
private-key	Y	Output	Is a PKCS #8-formatted private key. It is intended that the private key is stored in the secret store and not exposed directly in the configuration. See here for more details	`“pem file”`

Private key

The APNS binding needs 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
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
stringData:
    private-key: |
        -----BEGIN PRIVATE KEY-----
        KEY-DATA-GOES-HERE
        -----END PRIVATE KEY-----

Binding support

This component supports output binding with the following operations:

create

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 here.

Request format

{
    "data": {
        "aps": {
            "alert": {
                "title": "New Updates!",
                "body": "There are new updates 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 data object contains a complete push notification specification as described in the Apple documentation. The data object will be sent directly to the APNs service.

Besides the device-token value, the HTTP headers specified in the Apple documentation can be sent as metadata fields and will be included in the HTTP request to the APNs service.

Response format

{
    "messageID": "UNIQUE-ID-FOR-NOTIFICATION"
}

Last modified June 19, 2023: Merge pull request #3565 from dapr/aacrawfi/skip-secrets-close (b1763bf)

Apple Push Notification Service