LiveCode Lessons

How to send HTTP/2 based Push Notifications in iOS

Apple supports push notifications based on the HTTP/2 network protocol. In fact, the legacy binary protocol on which the previous LiveCode lesson was based, will no longer be supported, as of April 2021.

In this lesson, we will show how to send http/2 push notifications to an iOS app, using token authentication.

This lesson is structured into the following 5 logical sections:

1. Creating an App ID in your developer account and enabling the push notification entitlement.

2. Generating the signing key

3. Creating the Push Notification Provisioning Profile

4. Writing a LiveCode Application with Push Notification Support

5. Sending a Push Notification

1. Creating an App ID in your developer account and enabling the push notification entitlement.

Visit https://developer.apple.com/account and then go to Certificates, Identifiers & Profiles. Click on Identifiers and press the + icon to create a new identifier:

Choose App IDs and press Continue.

Choose App and press Continue.

Provide a Description and a Bundle ID. Ensure the Bundle ID does not contain an asterisk (*). Scroll down, and in the Capabilties section, enable Push Notifications, and click Continue.

Now click Register.

The new app ID is now registered. Now go back to the list of all app IDs, you should see the ID you just created:

2. Generating the signing key

Now go to the Keys section at the left pane:

Choose Create a key:

Provide a Key Name, enable Apple Push Notifications service (APNs), and click Continue

Then click Register

and then click Download

Store your key in a safe place. Make sure you write down your Key ID as well.

The key is a .p8 file, and its name should be something like AuthKey_<Key_ID>.p8

3. Creating the Push Notification Provisioning Profile

Each application that supports Push Notifications requires its own Provisioning Profile. The following steps lead you through the process of creating the Provisioning Profile for your application.

Log into your Apple Dev account and select Profiles on the left hand navigation panel. Click on the + button:

Choose iOS App Development and click Continue

In the App ID dropdown, choose the App ID you created in section 1 of this lesson, and click Continue.

In the next screen, choose the certificate(s) that you want to include in this provisioning profile, and click Continue.

In the next screen, choose the test devices on which the Provisioning Profile should operate, and click Continue.

Then provide a Provisioning Profile Name and click Generate.

In the next screen, click on Download

Then, double click on the downloaded profile to open it with Xcode. This will ensure that the profile will be selectable from within LiveCode.

4. Writing a LiveCode Application with Push Notification Support

Now that you have completed all of the work that is needed to support Push Notifications in LiveCode, it is time to implement code that acts upon a notification. Push Notifications are delivered by LiveCode in form of a message. Add the following or similar code to the stack script of your application:

on pushNotificationReceived pMessage
	  answer "Push Notification Message:" && quote & pMessage & quote with "Okay"
end pushNotificationReceived

Note: Look this message up in the dictionary and follow links to related dictionary entries.

Starting the application

The first time you start your Push Notification enabled LiveCode application you should get a message that is similar to the one shown here. The message only ever appears the first time the application is launched and does not appear again. This indicates that the iOS device is aware that the application can received Push Notifications and sets up the necessary parameters to allow notifications to be delivered to the application.

Getting the device identifier

The Device Identifier can be retrieved using the following LiveCode function:

mobileGetDeviceToken
answer the result with "Okay"

The Device Identifier is submitted to the server when registering for Push Notifications and provides the means by which the iOS device is identified when the notification is sent from the server.

Note: You don't get a deviceToken until after you get a Registered message. You can check this with the pushNotificationRegistered function

on pushNotificationRegistered pToken
   put ptoken into fld 1
end pushNotificationRegistered

5. Sending a Push Notification

Push Notifications are normally sent from a server, but we can simulate this action from a terminal. You can use the following code example as a template. Update the the first 6 lines with your own details and save it to a .sh file. In this example we are calling the file: send.sh

TEAM_ID=CDI79NSGHP
TOKEN_KEY_FILE_NAME=/Users/panos/Documents/PushNotificationAppAssets/NEW/AuthKey_9S733W8972.p8
AUTH_KEY_ID=9S733W8972
TOPIC=com.livecode.pushNotificationAppHttp2
DEVICE_TOKEN=62dfb121dfaa34c014rra9b4ed2d8ebcda43ed0ca7fafa8b7f45c512d60cdd30
APNS_HOST_NAME=api.sandbox.push.apple.com

JWT_ISSUE_TIME=$(date +%s)
JWT_HEADER=$(printf '{ "alg": "ES256", "kid": "%s" }' "${AUTH_KEY_ID}" | openssl base64 -e -A | tr -- '+/' '-_' | tr -d =)
JWT_CLAIMS=$(printf '{ "iss": "%s", "iat": %d }' "${TEAM_ID}" "${JWT_ISSUE_TIME}" | openssl base64 -e -A | tr -- '+/' '-_' | tr -d =)
JWT_HEADER_CLAIMS="${JWT_HEADER}.${JWT_CLAIMS}"
JWT_SIGNED_HEADER_CLAIMS=$(printf "${JWT_HEADER_CLAIMS}" | openssl dgst -binary -sha256 -sign "${TOKEN_KEY_FILE_NAME}" | openssl base64 -e -A | tr -- '+/' '-_' | tr -d =)
AUTHENTICATION_TOKEN="${JWT_HEADER}.${JWT_CLAIMS}.${JWT_SIGNED_HEADER_CLAIMS}"

curl -v --header "apns-topic: $TOPIC" --header "apns-push-type: alert" --header "authorization: bearer $AUTHENTICATION_TOKEN" --data '{"aps":{"alert":"You have a new message"},"payload":"Hello from LiveCode"}' --http2 https://${APNS_HOST_NAME}/3/device/${DEVICE_TOKEN}

From a terminal run your .sh file using this syntax (replace the file name with the name you created for the code):

sh /path/to/send.sh

panoss-MBP:~ panos$ sh /Users/panos/Documents/PushNotificationAppAssets/NEW/send.sh
*   Trying 17.188.166.29...
* TCP_NODELAY set
* Connected to api.sandbox.push.apple.com (17.188.166.29) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
* successfully set certificate verify locations:
*   CAfile: /etc/ssl/cert.pem
  CApath: none
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Request CERT (13):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Certificate (11):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
* ALPN, server accepted to use h2
* Server certificate:
*  subject: CN=api.development.push.apple.com; OU=management:idms.group.533599; O=Apple Inc.; ST=California; C=US
*  start date: Apr 17 17:37:51 2019 GMT
*  expire date: May 16 17:37:51 2021 GMT
*  subjectAltName: host "api.sandbox.push.apple.com" matched cert's "api.sandbox.push.apple.com"
*  issuer: CN=Apple IST CA 2 - G1; OU=Certification Authority; O=Apple Inc.; C=US
*  SSL certificate verify ok.
* Using HTTP2, server supports multi-use
* Connection state changed (HTTP/2 confirmed)
* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
* Using Stream ID: 1 (easy handle 0x7fdfa9002c00)
> POST /3/device/62dfb121dfaa34c01yhui9b4ed2d8ebcda4e140ca7fafa8b7f45c512d60cdd30 HTTP/2
> Host: api.sandbox.push.apple.com
> User-Agent: curl/7.54.0
> Accept: */*
> apns-topic: com.livecode.pushNotificationAppHttp2
> apns-push-type: alert
> authorization: bearer eyAiYWxnIjogIkVTMjU2hujgImtpZCI6ICI5Uzc5SjY4OTjhyiB9.eyAiaXNzIjogIktSNjQ5TlNHSFAiLCAiaWFoiuhgMTYxNTk4NzU5OSB9.MEUCICJ5C97K244rRLoLUyej1yPN4v1LU7BLuPeHe7dPzQeBAiEAtJsb5YNke93QVBxJCUY-5jsNJ60-bhooEjzw2_GZatY
> Content-Length: 74
> Content-Type: application/x-www-form-urlencoded
> 
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
* We are completely uploaded and fine
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
< HTTP/2 200 
< apns-id: 96FCFEF1-93EF-1086-A5D3-22UHYGA9DFAA
< 
* Connection #0 to host api.sandbox.push.apple.com left intact
panoss-MBP:~ panos$

After successfully running the script, you should see a notification in your device, displaying the alert part of the json data that is sent.

Tapping on the notification will open the app, and the pushNotificationReceived message will be sent to the stack, with the payload part of the json data:

Sending Push Notifications using LiveCode

Here is a sample stack, which you can use to send push notifications. You just need to fill in the details for:

Team ID
Signing Key (P8 Certificate)
Private Key ID
Bundle Identifier
Device Token
APNs Hostname

Then fill in the actual data you want to send, and click on the Send button:

sendHttp2PushNotifications.livecode

Note: There are several third party apps you can use to send push notifications, for example the PushNotifications utility.

Also, in a production environment, you should use

APNS_HOST_NAME=api.push.apple.com

instead of

APNS_HOST_NAME=api.sandbox.push.apple.com

The signing key you have created in the Apple Developer portal will be the same for both development and production environment.

For each notification, you provide a payload with app-specific information and details about how to deliver the notification to the user. The payload is a JSON dictionary object (as defined by RFC 4627) that you create on your server. The JSON dictionary object must contain an aps key. For more information, see here

Troubleshooting Common Issues

Here are a couple problems you might encounter:

No notifications arrive at the device: Make sure you have allowed the app to receive push notifications. You can check that in the Settings app. Also make sure you are connected to the Internet and the device clock is set to the correct date and time.

Some notifications arrive, but not all: If you’re sending many push notifications simultaneously but you receive only a few, this is expected. There is a queue of size 1, so if you send multiple notifications, the last notification is overridden.

Problem connecting to Push Notification Service: One possibility could be that there is a firewall blocking the ports used by APNs. Make sure you unblock these ports. Also, make sure the device is connected to the Internet, and the device clock is set to the correct date and time.

30 Comments

simon

Tuesday Jun 15 2021 at 07:19 PM

Hi team/Panos, many thanks for this excellent tutorial. It worked like a charm for me (except the sh part but probably I did something wrong). I'd like to know how can I add the badge number (the little red circle with the number) and also the Icon to be shown on the Alert. Many thanks in advance

Panos Merakos

Monday Jun 21 2021 at 12:03 PM

Hello Simon,

To add the badge number, you just have to include something like e.g.

"badge":5

in the JSON data, in the "aps" key. For example, in the sample stack, change this:

{
"aps":{"alert":"You have a new message"},
"payload":"Hello from LiveCode"
}

to this:

{
"aps":{"alert":"You have a new message","badge":5},
"payload":"Hello from LiveCode"
}

RE how to add the Icon to be shown on the alert, I need to investigate.

Were you able to add the icon previously (i.e. before the migration to http/2 push notifications)?

Kind regards,
Panos
--

Simon

Monday Jun 21 2021 at 12:33 PM

Panos, many thanks for your prompt and precise answer. Badge is showing as expected and please disregard the icon question, there is nothing to be done because iOS takes care of displaying the APP's icon.

Regards

Panos Merakos

Monday Jun 21 2021 at 12:45 PM

Thanks for the update, Simon.

simon

Tuesday Aug 03 2021 at 09:01 PM

For those who may be interested to play a sound when a notification arrives:
"sound":"ON"
has to be included in the JSON data, in the "aps" key, like this

"aps":{"alert":"You have a new message","badge":5,"sound":"ON"},

Trevix

Wednesday Aug 25 2021 at 07:53 AM

Hello. I am on OSX 10.15.7, Xcode 12.4, LC 9.6.3RC3, iOS 14.7.1 and iOS 14.4.2
I have a "test stack", for push notifications, the works just fine, registering on launch on iPhone.
This Test stack uses the same Provisioning profile and internal App ID of my real standalone, that refuses to register for push notification on launch.
Thinking of some code problem on launch or incompatible inclusions on the setting, I removed all the code from PreOpenStack (and open stack) and most inclusions on the Standalone settings, so that the App now opens and just stay there, without doing anything.
Still, the "pushNotificationRegistered", that is in the main stack script never gets fired.
Is it possible that there is something in the pList that interferes? Some other reasons?
Note that the same standalone, on Android, receives the "pushNotificationRegistered", so it is only a iOS problem.
I also tried to repeat this lesson, with all new data, on the standalone, to no result. On the test stack instead they work.
Thanks for any help or suggestion

Panos Merakos

Wednesday Aug 25 2021 at 09:10 AM

Hello Trevix,

A rough guess is that the name of the "real" standalone (in the iOS settings) has accented characters. I vaguely remember a similar issue in the past, affecting iOS 14, where if the standalone name contained accented characters, the pushNotificationRegistered msg was not sent.

Is this the case by any chance?

Kind regards,
Panos
--

Trevix

Wednesday Aug 25 2021 at 09:26 AM

No. The name of the standalone is "Segnapunto".
Searching on the forum for a solution, I also tried removing the splash image and also putting a "pushNotificationRegistrationError" (that doesn't get called).
I also tried removing the "answer pMessage" (used to understand what was happening) from the pushNotificationRegistered, replacing it with with a "put pMessage on old xx".
The test stack works on both iOS versions (an iphone and an iPad) while the standalone doesn't.
I guess that, under the wood, at launch the App notify something to the iOS: is there anyway to intercept what happens?

Panos Merakos

Wednesday Aug 25 2021 at 09:58 AM

Thanks for the follow up, Trevix. Hmm interesting. I think the best way to troubleshoot this is to send both stacks (the test one and the "real" one) to [email protected], so that we can have a closer look.

Kind regards,
Panos
--

Trevix

Thursday Aug 26 2021 at 12:59 PM

SOLVED: Thanks Panos. As always you are so helpful.
I had a custom pList that didn't fit.
I had to rebuild the custom pList from scratch, as from lesson, starting from the original LC generated one.

Regards
Trevix

Matthias Rebbe

Wednesday Sep 22 2021 at 10:45 PM

Hi. Thanks for this very helpful tutorial. Your sample stack for sending out the push notifications uses currently a shell script for the sending process. Is it not possible to just use LC with tsNET?

Panos Merakos

Thursday Sep 23 2021 at 10:07 AM

Hello Matthias,

I chose to write the shell script since it was easier for me to wrap the suggested curl command into a shell command. But I guess it should be possible to use tsNet for that. In fact it would be even better to have an example of doing this with tsNet, since people could use this stack not only on Mac (as this is the case with this stack, since it uses sh) but also on Windows.

So if you have a working example on how to do this with tsNet, it is very welcome :)

Kind regards,
Panos
--

Matthias Rebbe

Thursday Sep 23 2021 at 11:03 AM

>>So if you have a working example on how to do this with tsNet, it is very welcome :)<<
I was afraid you would write something like that... ;)

After i wrote my comment here yesterday i started with converting all parts of the script that create the JWT variables to Livecode syntax.
I am not sure if it's possible to create the JWT_SIGNED_HEADER_CLAIMS just with LC or if openssl is needed for that part. So at least that part needs to be done using the shell. As openssl is also available for Windows that would not be a problem. What do you think.

Simon

Monday Mar 21 2022 at 03:43 PM

Hi Panos, please disregard my previous message (again...). I found the reason why it wasn't working, I had accented characters both on the Alert and in the Payload fields, once removed (or UTF-8 encoded) then it works fine. As a suggestion I guess it should be mention in the lesson to be aware with the accents, they bite!!!

Panos Merakos

Monday Mar 21 2022 at 03:54 PM

Hello Simon,

Heh, I was just about to respond and ask you to check for accented characters in the standalone name (see https://quality.livecode.com/show_bug.cgi?id=22912). But it seems accented characters in the Alert and Payload fields cause an issue as well - good to know :)

Kind regards,
Panos
--

Ralph

Tuesday Apr 12 2022 at 09:05 PM

Hey!
Just got to iOS today and a couple of items. Again thanks to both of you for sorting most of this out. Works like a charm!
1) The spaces in the device identifier from either the registration or mobileGetDeviceToken must be removed. This bit me for an hour but no biggie. Of course I removed the brackets,
2 This might be an iOS characteristic? You lose the pushNotificationReceived message if you swipe the app off to close it, send a notification and click on the notification. The app opens but no message. Reboot and it works or re-install the app and it works. App must still be active is some way even if you swipe it off.
3) The last item. After using the "Apple purchase notification message" and dealing with JWT. The shell script looked suspiciously familiar. Your are doing the opposite of what I was doing last week, creating the 3 period delimited items. Is this possible in LCS? I need to have Win users send the notifications. I guess I can write an web API on the on-rev.com server to run the shell script or do it in LCS. The base 64 stuff with the 2 required substitutions in LCS is easy but it's the "openssl dgst -binary -sha256 -sign" that I don't have a handle on. Any suggestions?
Thanks

Panos Merakos

Wednesday Apr 13 2022 at 02:42 PM

Hello Ralph,

1. Yes, the Device ID string does contain spaces, which you have to remove.
2. Hmm, does it sound like this bug? https://quality.livecode.com/show_bug.cgi?id=10901
3. I believe it should be possible on Windows using tsNet, once this issue is fixed: https://quality.livecode.com/show_bug.cgi?id=23355

Otherwise, your idea of writing an web API on the on-rev.com server to run the shell script sounds like a good approach until bug 23355 is fixed.

Cheers,
Panos
--

Ralph

Wednesday Apr 13 2022 at 04:48 PM

Panos,
Thanks for the info! Any time frame for a tsNet update?
Also, if you want to send you notification text with some structure you can substitute the alert string with
{"title" : "Your title",
"subtitle" : "Your Subtitle",
"body" : "Your body text"}

This format is preferred by Apple.

Matthias Rebbe

Thursday Apr 14 2022 at 10:35 AM

@Ralph, according to a reply i received to a support request about this, the fix is planned to be included in LC 9.6.8.

Rodney Bradley

Thursday Mar 30 2023 at 05:21 AM

Hi
I am running your curl script from a .sh.
I am calling this .sh from a .php.
This .php is called from an Apple app running Xcode, (lets call the app, ROD).
The .php receives 2 $_REQUESTS from ROD. One is the DEVICE_TOKEN. the other is the "notification body text message".
The .php then calls the .sh using

shell_exec("sh sendhttps.sh $DEVICE_TOKEN $DEVICE_MESSAGE");
--------
$DEVICE_TOKEN and $DEVICE_MESSAGE are received by the .sh as "$1" and "$2".
The curl is then run from the .sh substituting your
https://${APNS_HOST_NAME}/3/device/${DEVICE_TOKEN}
with
https://${APNS_HOST_NAME}/3/device/$1

All the above works perfectly and the notification is received on the DEVICE.
And the "app" "alert" "body" is being displayed .eg. "Rod needs help".
This is my problem?
I am trying to replace the "body" text with the text in $2.
$2 contains the text "Coming from the server".
BUT no matter what syntax I use the "body" on the devices notification only ever shows "Coming".
with nothing else displaying after the 1st space?

What would the syntax be to display the entire text in $2.

My curl is below...
curl -ivk --header "apns-topic: $TOPIC" --header "apns-push-type: alert" --header "authorization: bearer $AUTHENTICATION_TOKEN" --data '{"aps":{"alert": {"title": "NEW message.", "body": "'$2'"}}}' --http2 https://${APNS_HOST_NAME}/3/device/$1 >> /Users/s----------/S--------/logs/send_to_each_device.log

Is using $2 in the "body" even possible?
Any help would be greatly appreciated.

Panos Merakos

Thursday Mar 30 2023 at 03:36 PM

Hello Rodney,

It sounds like you need to escape spaces? What happens if instead of "Coming from the server" you use "Coming\ from\ the\ server" ?

Kind regards,
Panos

Dictionary

Guides

Lessons

Courses

LiveCode Lessons

How to send HTTP/2 based Push Notifications in iOS

1. Creating an App ID in your developer account and enabling the push notification entitlement.

2. Generating the signing key

3. Creating the Push Notification Provisioning Profile

4. Writing a LiveCode Application with Push Notification Support

5. Sending a Push Notification

30 Comments

Add your comment

Topics

Last Updated

Other Resources

Getting Started with LiveCode

LiveCode Lessons

Tutorials

Data Grid

LiveCode Releases

LiveCode Builder