Hide last authors
Sylvain Berfini 5.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc /}}
3 {{/box}}
4
François Grisez 13.1 5 = Overview =
6
François Grisez 14.1 7 PushNotification module allows Flexisip to wake a liblinphone-basd application up when a chat message or call invite cannot be delivered because the application is unavailable. This feature has become crucial since mobile OSs got used to making the application to hibernate in order to save power.
8
9 Today, Flexisip supports native push systems of Android, iOS and Windows Phone ; but can also delegate the work of sending the push request to a tier service using HTTP GET API.
10
François Grisez 13.1 11 = Enabling Push Notifications =
12
François Grisez 14.2 13 First, enable the PushNotification module.
François Grisez 10.1 14
15 {{code}}
François Grisez 14.2 16 [module::PushNotification]
17 enabled=true
18 {{/code}}
19
20 Applications notify Flexisip of their push IDs by using custom parameters in their REGISTER requests, so that Flexisip is able to send push requests to a given application if this one is still register. Thus, expire time of a REGISTER influence how long an application can be woken up, so you should set Flexisip to authorize high expire value.
21
22 {{code}}
François Grisez 10.1 23 [module::Registrar]
François Grisez 14.2 24 # Allow applications to be woken up for 7 days
25 # after their last REGISTER.
François Grisez 10.1 26 max-expires=604800
27 {{/code}}
28
François Grisez 14.2 29 Furthermore, by default, Flexisip immediately give up call session establishment or delivering a message when the destination isn't available. Thus, the application won't be able to receive the call invitation or the chat message for which it has been woken up because it simply has been dropped by the proxy. ##fork-late## in ##module::Router## section must be set to ##true## to allow the proxy to hold call invitations and chat messages for a given time before dropping them.
30
François Grisez 10.1 31 {{code}}
32 [module::Router]
33 fork-late=true
François Grisez 14.2 34
35 # Make chat messages to be hold for 7 days
36 # before to be dropped. Call invitations are hold for 32s
37 # in conformance with RFC 3261.
François Grisez 10.1 38 message-delivery-timeout=604800
39 {{/code}}
40
François Grisez 34.1 41 = Configuring for each mobile platform =
François Grisez 10.1 42
43 == Apple ==
44
François Grisez 39.1 45 (% class="wikigeneratedid" id="HMaketheauthenticationcertificates" %)
46 **Make the authentication certificates**
François Grisez 10.1 47
François Grisez 30.1 48 Apple push authentication service authenticates the nodes which are authorized to send push notification by using client TLS certificates. Following instructions
François Grisez 10.1 49
François Grisez 30.1 50 1. On macOS, open //Keychain Access > Certificate Assistant > Request a certificate from a Certificate Authority//. Enter your email and check "Saved to disk" box (this file will be deleted soon).
51 1. Connect to [[Apple developer website>>https://developer.apple.com/account/ios/certificate/certificateCreate.action]] and ask for an Apple Push Notification Service SSL certificate (either SandBox or Production)
52 1. Select your application in the list and select the file you generated earlier when a CSR file is requested. Finalize the procedure.
53 1. Now, you must export your certificate (named "Apple Development iOS Push Services: <bundle-id>"), including the private key from Keychain Access, to p12 format.
54 1. Then, you need to convert your p12 certificate into PEM format. The PEM certificate MUST NOT be protected by a password. OpenSSL utilities may be used for such conversion:
55 1*. for Sandbox certificates: {{code}}openssl pkcs12 -nodes -in <generated-file>.p12 -out <bundle-id>.dev.pem{{/code}}
56 1*. for Production certificates: {{code}}openssl pkcs12 -nodes -in <generated-file>.p12 -out <bundle-id>.prod.pem{{/code}}
57
François Grisez 39.1 58 (% class="wikigeneratedid" id="HConfigureFlexisip" %)
59 **Configure Flexisip**
François Grisez 10.1 60
François Grisez 30.1 61 To enable Apple push notification you just need to set ##apple=true## and place the certificates you made earlier in ##/etc/flexisip/apn##. The directory where to place Apple push certificates may be changed using ##apple-certificate-dir## parameter.
François Grisez 10.1 62
François Grisez 31.1 63 {{code}}
64 [module::PushNotification]
65 apple=true
66 {{/code}}
67
François Grisez 29.1 68 == Android (Firebase) ==
François Grisez 11.1 69
François Grisez 40.1 70 (% class="wikigeneratedid" id="HRegisteryourapplicationonFirebaseservice" %)
71 **Register your application on Firebase service**
François Grisez 23.1 72
François Grisez 29.1 73 [[Sign in into Firebase>>https://console.firebase.google.com/?authuser=0]] and follow [[Add Firebase using the Firebase console>>https://firebase.google.com/docs/android/setup?authuser=0#console]] procedure. Steps 3 and 4 may be skipped.
François Grisez 23.1 74
François Grisez 40.1 75 (% class="wikigeneratedid" id="HFlexisipconfiguration" %)
76 **Flexisip configuration**
François Grisez 11.1 77
François Grisez 38.1 78 Enable the ##firebase## backend and set ##firebase-projects-api-keys## parameter, where## <sender_id>## and ##<server_key>## can be gotten form Firebase console in //"Settings" section > "Cloud messaging" tab//.
François Grisez 11.1 79
80 {{code language="ini"}}
81 [module::PushNotification]
82 firebase=true
83 firebase-projects-api-keys=<sender id>:<server key>
84 {{/code}}
85
François Grisez 10.1 86 = Testing =
87
François Grisez 41.1 88 You may test that your server-side configuration is ok by using the //flexisip-pusher //tool embedded in the Flexisip installation package. It enables to manually send a notification request to the push notification server. You may invoke //flexisip-pusher// using the following:
François Grisez 10.1 89
François Grisez 22.1 90 {{code language="bash"}}
François Grisez 41.1 91 ./flexisip_pusher --pn-provider <provider> --pn-param <params> --pn-prid <prid> --debug
François Grisez 10.1 92 {{/code}}
93
François Grisez 41.1 94 (% class="wikigeneratedid" %)
95 where **<provider>**, **<params>** and **<prid>** indicate which push server to use and all the information required to send a push notification to a specific device, as normalized by [[rfc8599>>https://datatracker.ietf.org/doc/html/rfc8599]]. A summary of the possible values is also available [[in our « Push notification » specification>>doc:Flexisip.D\. Specifications.Push notifications.WebHome||anchor="HRequestingPushNotificationswhileregisteringtheSIPuseragent"]].
96
François Grisez 10.1 97 == Testing on iOS ==
98
François Grisez 41.1 99 To send a classic « Remote » push notification:
François Grisez 10.1 100
François Grisez 22.1 101 {{code language="bash"}}
François Grisez 41.1 102 ./flexisip_pusher --pn-provider apns.dev --pn-param ABCD1234.<bundle-id> --pn-prid <token> --apple-push-type RemoteBasic --debug
François Grisez 10.1 103 {{/code}}
104
François Grisez 41.1 105 To send a VoIP push notification:
106
107 {{code language="bash"}}
108 ./flexisip_pusher --pn-provider apns.dev --pn-param ABCD1234.<bundle-id>.voip --pn-prid <token> --apple-push-type PushKit --debug
109 {{/code}}
110
François Grisez 41.3 111 Check the the following message to know whether the push request has been successfully sent:
François Grisez 10.1 112
François Grisez 20.1 113 {{code language="none"}}
François Grisez 41.3 114 1 push notification(s) sent, 1 successfully and 0 failed.
François Grisez 20.1 115 {{/code}}
François Grisez 10.1 116
117 If you get the following error:
118
François Grisez 21.1 119 {{code language="none"}}
François Grisez 10.1 120 E: PNR 0x7fed1a449858 with identifier 1 failed with error 8 (Invalid token)
121 {{/code}}
122
123 It probably means that you are using the wrong application id. Note: to test the production certificate, you must generate an adhoc IPA and install it manually!
124
François Grisez 12.1 125 == Testing on Android ==
Sylvain Berfini 1.1 126
François Grisez 41.2 127 Here's how to send an Android (Firebase) push notification:
Sylvain Berfini 5.1 128
François Grisez 22.1 129 {{code language="bash"}}
François Grisez 41.1 130 ./flexisip_pusher --pn-provider fcm --pn-param <ProjectID> --pn-prid <device_token> --key <secret_key> --debug
Sylvain Berfini 5.1 131 {{/code}}