Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = Overview =
6
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
11 = Enabling Push Notifications =
12
13 First, enable the PushNotification module.
14
15 {{code}}
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}}
23 [module::Registrar]
24 # Allow applications to be woken up for 7 days
25 # after their last REGISTER.
26 max-expires=604800
27 {{/code}}
28
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
31 {{code}}
32 [module::Router]
33 fork-late=true
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.
38 message-delivery-timeout=604800
39 {{/code}}
40
41 = Configuring for each mobile platform =
42
43 == Apple ==
44
45 (% class="wikigeneratedid" id="HMaketheauthenticationcertificates" %)
46 **Make the authentication certificates**
47
48 (% class="wikigeneratedid" %)
49 Flexisip uses TLS client certificate way to authenticate itself to the Apple Push Notification Service. Thus, a client certificate must be created and signed by Apple's certification authority for each application which you need to send push notifications to. The following procedure will guide you to make and install a certificate in order your Flexisip instance be able to send notifications to your application:
50
51 ~1. [[Create a Certificate Signing Request (CSR)>>https://help.apple.com/developer-account/#/devbfa00fef7]].
52
53 2. Follow [[this guide>>https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_certificate-based_connection_to_apns#dev9249db258]] to make Apple's authority to sign your CSR. Just follow **“Obtain a Provider Certificate from Apple”** section.
54
55 3. At this point, you got one pkcs12 file which contains your signed certificate and the associated private key. Unfortunately, Flexisip expects PEM-formated certificates, so you need to use OpenSSL command-line tool to convert your certificate in this format:
56
57 {{code language="none"}}
58 $ openssl pkcs12 -nodes -in <certificate-given-by-apple>.p12 -out <app-id>.prod.pem
59 {{/code}}
60
61 Please note that the name of the generated PEM file is imposed by Flexisip.
62
63 4. It is highly recommended to also make a VoIP certificate as those are required when Flexisip needs to send a push notification for audio/video call invitations. To do so, you just need to repeat step 1 to 3 but selecting **“VoIP Services Certificate”** instead of **“Apple Push Notification service SSL (Sandbox & Production)”** while carrying out step 2. The name of the generated PEM file must be changed in step 3 to avoid collision with the previously made certificate:
64
65 {{code language="none"}}
66 $ openssl pkcs12 -nodes -in <certificate-given-by-apple>.p12 -out <app-id>.voip.prod.pem
67 {{/code}}
68
69 5. Push all your PEM certificates onto your Flexisip host server into **/etc/flexisip/apn** directory.
70
71 6. Create a symbolic link for each newly added certificate in order Flexisip be able to send push notifications to your in-development application:
72
73 {{code language="none"}}
74 $ cd /etc/flexisip/apn
75 $ ln -s <app-id>.{prod,dev}.pem
76 $ ln -s <app-id>.voip.{prod,dev}.pem
77 {{/code}}
78
79 **Configure Flexisip**
80
81 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.
82
83 {{code}}
84 [module::PushNotification]
85 apple=true
86 {{/code}}
87
88 == Android (Firebase) ==
89
90 (% class="wikigeneratedid" id="HRegisteryourapplicationonFirebaseservice" %)
91 **Register your application on Firebase service**
92
93 [[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.
94
95 (% class="wikigeneratedid" id="HFlexisipconfiguration" %)
96 **Flexisip configuration**
97
98 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//.
99
100 {{code language="ini"}}
101 [module::PushNotification]
102 firebase=true
103 firebase-projects-api-keys=<sender id>:<server key>
104 {{/code}}
105
106 = Testing =
107
108 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:
109
110 {{code language="bash"}}
111 ./flexisip_pusher --pn-provider <provider> --pn-param <params> --pn-prid <prid> --debug
112 {{/code}}
113
114 (% class="wikigeneratedid" %)
115 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"]].
116
117 == Testing on iOS ==
118
119 To send a classic « Remote » push notification:
120
121 {{code language="bash"}}
122 ./flexisip_pusher --pn-provider apns.dev --pn-param ABCD1234.<bundle-id> --pn-prid <token> --apple-push-type RemoteBasic --debug
123 {{/code}}
124
125 To send a VoIP push notification:
126
127 {{code language="bash"}}
128 ./flexisip_pusher --pn-provider apns.dev --pn-param ABCD1234.<bundle-id>.voip --pn-prid <token> --apple-push-type PushKit --debug
129 {{/code}}
130
131 Check the the following message to know whether the push request has been successfully sent:
132
133 {{code language="none"}}
134 1 push notification(s) sent, 1 successfully and 0 failed.
135 {{/code}}
136
137 If you get the following error:
138
139 {{code language="none"}}
140 E: PNR 0x7fed1a449858 with identifier 1 failed with error 8 (Invalid token)
141 {{/code}}
142
143 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!
144
145 == Testing on Android ==
146
147 Here's how to send an Android (Firebase) push notification:
148
149 {{code language="bash"}}
150 ./flexisip_pusher --pn-provider fcm --pn-param <ProjectID> --pn-prid <device_token> --key <secret_key> --debug
151 {{/code}}