Requirements for this tutorial:
- Basic knowledge of API’s
- Live app in the store(s) so you can test this feature
In Part 1 we discussed the Push Notification section and created categories in the app. We then sent a push message to all the users subscribed to a specific category.
In Part 2, we will discuss the User Section of the API and we will send a personal push notification to a specific user.
Let’s begin:
As always have to send these two things in the headers of your API call for authentication purposes. In Part 1 you can read where to find them in your app. So we won’t go into further detail about that now. You will need:
- AM-AppKey
- AM-ClientKey
The API Calls for the User Section
Let's take a look at all of the calls you can make in this section.
GET /v1/users
Will retrieve a list of all the users that are registered in your app.
GET /v1/users/{accountId}/devices
Will get a list of all the devices that are registered for push notifications from one registered user in your app. This way you can send a message to a user's iPhone but not his Android device, because the user never has it with him.
What we will do:
- Getting all the users that are registered in your app.
- Getting the devices from the user that can receive push notifications.
- Send a personal push notification to the user
Check if there are registered users available in our app.
GET v1/users
The response of the API call should give us back all the users that are registered in your app. The output looks like this:
As you can see, you will find some familiar “keys” in the output. Some of them are the same fields as when a user registers in the app.
“fullName” “emailAddress” “phoneNumber” “ageRange” “gender”.
All we really need here is the “id” field to get the devices for that users that can can receive push messages.
So let’s go and fill in your AM-AppKey and AM-ClientKey (emailAddress is optional, when you fill this in you can filter by user and you will get one result back if the email address belongs to a registered user)
After that we can try it out and it will hopefully return something back. The Error messages are explained above the "try it out" button should you get one.
It looks like our call was successful and we have gotten a list of all our users (34 in total registered in the app), including me :)
Let’s save the id in a text editor like Sublime, TextEdit or any other program of your choosing, because we need this in the GET devices API call.
Getting Device Token(s)
Step 2 is to get the deviceToken of the user to which we want to send the push notification. Let’s go and see what that call does.
GET /V1/Users/{accountid}/devices
The response is:
Parameters explained (result)
"platform" = can be iOS or Android
"pushNotificationEnabled" = If the device has accepted to receive push notifications. This can be true or false.
"pushNotificationToken" = The token for the device that we need. This is a long range of numbers & letters.
Let’s fill in the AM_AppKey & AM_ClientKey + accountId and let’s see what we get.
Result output
Yes! Looks like I (Johnny) have 2 devices available for receiving push notifications.
*Note: PushNotificationToken is actually the deviceToken. The Naming convention will be adjusted later in the API. From here on, I will refer to the PushNotificationToken as “deviceToken”.
Once again, save one deviceToken in a text editor by choice since we need it alongside the userId. I will be saving my iOS deviceToken.
Sending a Push Notification to a User
So what we've done so far:
Checking if our live-app has registered users.
Saved the “id“ field of a registered user in a text editor
Checked if the user has devices that can receive push notifications.
Saved the “deviceToken” in a text editor program
Now it's finally time to send a push notification to one of the users (i.e. me, "Johnny").
Please note!: App users need to be registered in the app. Also the app needs to be available in the store(s) for the push notification to be sent.
The call to send the push notification is of course the POST PushNotifcation call
We already explained what this call does inPart 1 so we will skip that for now and go straight to the body parameter. The important part of the “body” parameter is the userId field and deviceToken field.
Copy/paste the userId + DeviceToken that you saved in your text editor field as the value.
Also type a message and decided if you want a badge number to show up in the app icon when a push notification is received on the device. If set to “1” it will show the badge, if set to “0” it will not display the badge.
My Body Parameter looks like this.
So I filled in the message / badge / userId and the deviceToken. So once you've got that right press the “Try it now” button and see if you receive the push notification on the device you have entered in the deviceToken.
Send Push Notification to a group of users
You can follow the steps we completed for getting the user list to find and save the userIds that you want to send a message to so that you can insert them in the userids field "," separated like:
"userids": {
"userId1","userId2","userid3"
}
You can remove the highlighted part "deviceTokens".
It will send the message to all the devices that the users have registered.
If you want you can also fill in the deviceTokens for those users if you want to get specific.
* Note: You have to be signed in with the email address that corresponds with the userId into the app to receive the push notification. In this case I’m signed in with johnny@appmachine.com