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.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: <NAME>
  5. spec:
  6.   type: bindings.apns
  7.   version: v1
  8.   metadata:
  9.     - name: development
  10.       value: "<bool>"
  11.     - name: key-id
  12.       value: "<APPLE_KEY_ID>"
  13.     - name: team-id
  14.       value: "<APPLE_TEAM_ID>"
  15.     - name: private-key
  16.       secretKeyRef:
  17.         name: <SECRET>
  18.         key: "<SECRET-KEY-NAME>"

Spec metadata fields

FieldRequiredBinding supportDetailsExample
developmentYOutputTells 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-idYOutputThe identifier for the private key from the Apple Developer Portal“private-key-id“
team-idYOutputThe identifier for the organization or author from the Apple Developer Portal“team-id”
private-keyYOutputIs 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:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: apns
  5. spec:
  6.   type: bindings.apns
  7.   metadata:
  8.   - name: development
  9.     value: false
  10.   - name: key-id
  11.     value: PUT-KEY-ID-HERE
  12.   - name: team-id
  13.     value: PUT-APPLE-TEAM-ID-HERE
  14.   - name: private-key
  15.     secretKeyRef:
  16.       name: apns-secrets
  17.       key: private-key

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

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.     name: apns-secrets
  5. stringData:
  6.     private-key: |
  7.         -----BEGIN PRIVATE KEY-----
  8.         KEY-DATA-GOES-HERE
  9.         -----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

  1. {
  2.     "data": {
  3.         "aps": {
  4.             "alert": {
  5.                 "title": "New Updates!",
  6.                 "body": "There are new updates for your review"
  7.             }
  8.         }
  9.     },
  10.     "metadata": {
  11.         "device-token": "PUT-DEVICE-TOKEN-HERE",
  12.         "apns-push-type": "alert",
  13.         "apns-priority": "10",
  14.         "apns-topic": "com.example.helloworld"
  15.     },
  16.     "operation": "create"
  17. }

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

  1. {
  2.     "messageID": "UNIQUE-ID-FOR-NOTIFICATION"
  3. }