Apple Push Notifications Service (APNS)

Setup

Setup Video

1. Go to your Apple Developer Account
2. Click "Certificates"
3. Click "Keys"
4. Click the "+" button
5. Name the Key
6. Click "Enable" on "Apple Push Notifications Service (APNs)"
7. Click "Continue"
8. Click "Register"
9. Click "Download"
10. Go to the APNS Provider Configuration
11. Enter the required information
12. Click "Install Provider" or "Save"

Getting APNS Tokens

With a Courier Mobile SDK

Using a Courier Mobile SDK is the best way to set this up. All Courier Mobile SDKs sync APNS tokens to Courier and will be automatically managed. This allows you to send pushes directly to a user_id rather than APNS tokens.

Mobile SDK	APNS Token Management	Tracking Analytics
iOS	Automatic	Automatic
Android	Not Supported	Not Supported
React Native	Automatic	Automatic
Flutter	Automatic	Automatic

Without a Courier Mobile SDK

Follow Apple's Documentation to setup push notifications on your iOS device.

What APNS tokens look like:

469d754f85604fa6bcf98c4299ba9aa760a5a3b01c5ca7277342cf3fbcea5c91

Manual Implementation Requirements

You will need to sync, store, and manage your user's APNS tokens. This likely will require you to create entries in your database, deploy separate endpoints, and add extra development time that can be avoided with a Courier Mobile SDK.

If you'd like Courier delivery and click tracking, you will also need to manually make a request to the trackingUrl.

Sending Messages

This is a common example request you can make to the send api that shows:

1. providers.apn.override.body.aps.YOUR_CUSTOM_KEY for adding custom data to your payload. This is usually used for opening a specific screen in your app when the user takes action on a push notification.
2. providers.apn.override.body.aps for applying iOS specific values. You can learn more about these here.

ClickAction and Data Mapping

In order to pass a click action link into your push notification, you will need to enable the data mapping toggle in the Push channel settings.

Data mapping enabled

You can then perform a send request that looks similar to this, passing the clickAction in the data payload.

{
    "message": {
        "to": {
            "user_id": "mike_mill_made_it"
        },
        "template": "HY59FFJQTR4JGEGT25HQD2D201GK",
        "data": {
            "click_action": "https://courier.com"
        }
    }
}

Push Sound & Badging

Sounds and badges can only be configured in the override schema of a send request at this time, and are not compatible with a template field attached. If your push notifications require sounds and badges, then we recommend shaping your push request with sound and badge in the override as shown below.

Sending to a user_id (Recommended)

curl --request POST \
  --url https://api.courier.com/send \
  --header 'Authorization: Bearer YOUR_AUTH_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"message": {
		"to": {
			"user_id": "YOUR_USER_ID"
		},
		"content": {
			"title": "Hey there 👋",
			"body": "Have a great day 😁"
		},
		"routing": {
			"method": "all",
			"channels": [
				"apn"
			]
		},
		"providers": {
			"apn": {
				"override": {
					"body": {
						"aps": {
							"alert": {
								"title": "Hey there 👋",
								"body": "Have a great day 😁"
							},
							"sound": "ping.aiff",
							"badge": 99,
							"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
						}
					}
				}
			}
		}
	}
}'

Silent Messages

curl --request POST \
  --url https://api.courier.com/send \
  --header 'Authorization: Bearer YOUR_AUTH_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"message": {
		"to": {
			"user_id": "YOUR_USER_ID"
		},
		"content": {
			"title": "...",
			"body": "..."
		},
		"routing": {
			"method": "all",
			"channels": [
				"apn"
			]
		},
		"providers": {
			"apn": {
				"override": {
					"silent": true,
					"body": {
						"badge": 123
					}
				}
			}
		}
	}
}'

Sending to a token

curl --request POST \
  --url https://api.courier.com/send \
  --header 'Authorization: Bearer YOUR_AUTH_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"message": {
		"to": {
			"apn": {
				"token": "YOUR_APNS_TOKEN"
			}
		},
		"content": {
			"title": "Hey there 👋",
			"body": "Have a great day 😁"
		},
		"routing": {
			"method": "all",
			"channels": [
				"apn"
			]
		},
		"providers": {
			"apn": {
				"override": {
					"body": {
						"aps": {
							"alert": {
								"title": "Hey there 👋",
								"body": "Have a great day 😁"
							},
							"sound": "ping.aiff",
							"badge": 99,
							"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
						}
					}
				}
			}
		}
	}
}'

Sending to multiple tokens

curl --request POST \
  --url https://api.courier.com/send \
  --header 'Authorization: Bearer YOUR_AUTH_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"message": {
		"to": {
			"apn": {
				"tokens": ["APNS_TOKEN_ONE", "APNS_TOKEN_TWO"]
			}
		},
		"content": {
			"title": "Hey there 👋",
			"body": "Have a great day 😁"
		},
		"routing": {
			"method": "all",
			"channels": [
				"apn"
			]
		},
		"providers": {
			"apn": {
				"override": {
					"body": {
						"aps": {
							"alert": {
								"title": "Hey there 👋",
								"body": "Have a great day 😁"
							},
							"sound": "ping.aiff",
							"badge": 99,
							"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
						}
					}
				}
			}
		}
	}
}'

Automatic Courier Mobile SDK Formatting

By default, Courier automatically formats parts of the APNS payload to make a better developer experience for you if you are working with a Courier Mobile SDK. Here you can manage the automatic APNS settings.

What this setting does:

1. Creates a simple toggle to send to Apple's production or sandbox push notification environment. Production (switch is on) is used in your production app and Sandbox (switch is off) is used for testing and development. More Details
2. "Attach Mutable Content" supports Courier's iOS Notification Service Extension for better push notification delivery tracking.