Show last authors
1 (% class="row" %)
2 (((
3 (% class="col-xs-12 col-sm-8" %)
4 (((
5
6
7 = Adding the liblinphone dependency to your iOS project =
8
9 Liblinphone for iOS is available using [[Cocoapods>>https://cocoapods.org]], the de-facto standard in the Apple developer world for "dependency management for Swift and Objective-C". Liblinphone can also be compiled from the sources.
10
11 Using Cocoapods
12
13 For a project named "Myproject"
14
15 open Myproject/, use commands:
16
17 {{code}}
18 pod init
19 {{/code}}
20
21 Modify the generated Podfile according to your project:
22
23 {{code}}
24 # Uncomment the next line to define a global platform for your project
25
26 ##For macosx
27 # platform :osx, '10.9'
28 #source "https://gitlab.linphone.org/BC/public/podspec-macos.git"
29
30 #For iOS
31 platform :ios, '9.0'
32 source "https://gitlab.linphone.org/BC/public/podspec.git"
33
34 target 'Myproject' do
35 use_frameworks!
36
37 # Pods for Myproject
38 pod 'linphone-sdk' , '4.5'
39 end
40
41 {{/code}}
42
43 To install or update the liblinphone version, do the following command
44
45 {{code}}
46 pod repo update
47 pod install
48 {{/code}}
49
50 == ==
51
52 And you're done.
53
54 Some alpha (development versions) of liblinphone may also be available. To get them, replace the line:
55
56 {{box}}
57 pod 'linphone-sdk' , '4.5'
58 {{/box}}
59
60 by
61
62 {{code}}
63 pod 'linphone-sdk', '> 5.0.0-alpha'
64 {{/code}}
65
66 followed by:
67
68 {{code}}
69 pod install
70 {{/code}}
71
72 == Compiling linphone-sdk ==
73
74 Linphone-sdk is the name of the git project that contains liblinphone and all its dependencies.
75
76 Compilation instructions of the SDK are available at: [[linphone-sdk/README.md>>https://gitlab.linphone.org/BC/public/linphone-sdk/blob/master/README.md]]
77
78 Once done, cocoapods needs to be invoked to update the Xcode workspace to use your locally built linphone-sdk, as follows:
79
80 {{code language="sh"}}
81 PODFILE_PATH=<path to linphone-sdk-ios> pod install
82 {{/code}}
83
84 {{{where <path to linphone-sdk-ios> is your build directory of the linphone-sdk project, containing the linphone-sdk.podspec file and a linphone-sdk output directory comprising built frameworks and resources.
85 }}}
86
87 = Using liblinphone =
88
89 Liblinphone has a C API, suitable to be used with Objective-C, and a modern Swift API. To use in swift, import the liblinphone swift module in your source file using
90
91 {{code}}
92 import linphonesw
93 {{/code}}
94
95 == API documentation ==
96
97 You can find the liblinphone C API documentation [[here>>https://www.linphone.org/snapshots/docs/liblinphone/c]].
98
99 For Swift, online documentation is available [[here>>https://www.linphone.org/snapshots/docs/liblinphone/swift]] . In addition, this [[iOS sample app>>https://gitlab.linphone.org/linphone-tutorial/linphone-swift-tutorial]] shows how to use liblinphone in a Swift project.
100
101 = Guidelines for integrating with push notifications =
102
103 == Introduction ==
104
105 An iOS application has in general a very limited capability to run in background, for example to keep a connection to a SIP server in order to receive calls and IM at any time. **When the application goes in background, the network connections are killed and the application no longer executes.**
106
107 The solution to circumvent this limitation is to rely on **Apple's push notification** system. The push notification first launch or resumes the app, that can then connect to the SIP service and retrieve the pending INVITE or MESSAGE request. In iOS there are three kinds of push notifications:
108
109 * The [[Remote Notification>>https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/HandlingRemoteNotifications.html#//apple_ref/doc/uid/TP40008194-CH6-SW1]], for general purpose notifications
110 * The [[PushKit notifications>>https://developer.apple.com/documentation/pushkit]], dedicated to VoIP calls. Unlike Remote Push Notifications, they do not display anything by themselves.
111 * The [[Background Update Notifications>>https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app]], used for service like notifications. They are not real-time and severely rate limited (no more than 3 per hour). They are currently not used by Linphone, liblinphone or Flexisip.
112
113 **New limitations and restrictions were added by Apple with Xcode 11 and iOS 13:**
114
115 * **applications can no longer use PushKit kind of push notifications for anything else than presenting a VoIP call with CallKit**. This is disruptive because previously, communication apps tend to also use PushKit to get notified of incoming IM messages. Since they can wake up the app in background, it was convenient to perform background processing before displaying the message to the user.
116 * **applications receiving a PushKit notification are required to immediately invoke Callkit to display the call to the end-user.** This is disruptive also, because at the time of receiving the push notification, the app has not yet the signaling information about the call (ie, the SIP INVITE). The end user may even accept the call while the INVITE is not yet arrived, in which case the app has to postpone the call acceptance to the actual receiving of the INVITE, and also update the CallKit view with the missing information.
117
118 The next chapters explain the detailed steps to create a Liblinphone based application that comply with the above requirements. It can be used of course as a guide to upgrade an existing liblinphone based application to iOS 13 / Xcode 11.
119
120 (% class="box infomessage" %)
121 (((
122 Please note that an iOS application compiled with Xcode 10 still executes normally on iOS 13. The disruption happens only while compiling with Xcode 11.
123 )))
124
125 == Technical solutions to advertise incoming calls ==
126
127 The table below summarizes the technical solutions offered to advertise incoming calls.
128
129 |=Use case|=Push notification type|=Solution
130 |App showing calls with **Callkit**, with access to internet.|[[Pushkit>>https://developer.apple.com/documentation/pushkit]]|(((
131 Integrate CallKit into your application according to the guidelines provided in the section "[[Callkit integration>>doc:||anchor="Callkit integration"]]" of this document.
132
133 This solution is the one implemented in the Linphone application.
134 )))
135 |App showing calls with **Callkit**, in an isolated network.|No push notification at all.|(((
136 Use UIApplication's [[keepAliveTimeout>>https://developer.apple.com/documentation/uikit/uiapplication/1622989-setkeepalivetimeout]] to trigger periodic calls to [[Core.refreshRegisters()>>https://www.linphone.org/snapshots/docs/liblinphone/swift/Classes/Core.html#/s:10linphonesw4CoreC16refreshRegistersyyF]] and [[background sockets>>https://developer.apple.com/documentation/foundation/nsstreamnetworkservicetypevoip?language=objc]]. Use Callkit in your app, but without Pushkit. Liblinphone by default attempts to activate background sockets.
137
138 **Using this solution requires a special authorization from Apple. The app must have its main usage done without connection to the internet.**
139 )))
140 |(((
141 Basic app **not showing calls with Callkit.**
142
143 This is the case where the Callkit UI is not adapted.
144
145 For example: an app that needs to establish video at first, home automation app showing video before the call is accepted.
146 )))|[[Remote Push Notifications>>https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns]]|(((
147 Use [[Remote Push Notifications>>https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns]] in a basic scheme.
148
149 * They will play a sound and vibrate once.
150 * They cannot be cancelled (for example if the caller cancels the call).
151 * The caller identity must be added by the SIP server in the remote push notification in order to be shown to the user.
152
153 When pressed by the user, the notification will launch or resume the app. The app can then connect to the SIP service and display the incoming call in its UI.
154 )))
155 |(((
156 **Advanced** app **not showing calls with Callkit**.
157
158 This is the case where the Callkit UI is not adapted.
159
160 For example: an app that needs to establish video at first, home automation app showing video before the call is accepted.
161 )))|[[Remote Push Notifications>>https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns]] used together with a [[Notification Content Extension>>https://developer.apple.com/documentation/usernotificationsui/unnotificationcontentextension]]|(((
162 Use [[Remote Push Notifications>>https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns]], but handle them inside an app extension of type "[[Notification Content>>https://developer.apple.com/documentation/usernotificationsui/unnotificationcontentextension]]". The app extension is a companion bundled with main application. It executes in a different process with restricted permissions, for example it cannot access geolocation information.
163
164 * The app extension can vibrate repeatedly
165 * The app extension can wait for the INVITE to be received, present caller information, and can be cancelled if the caller cancelled the call.
166 * The app extension can show video received as early-media in the notification area.
167
168 When the notification is pressed by the user, the main app is resumed or launched. The app extension stops, and the call needs to be received a second time by the main app. The main app can know if the user has accepted the call in the notification, and then immediately transition the call to a running state.
169 )))
170
171 (% class="box infomessage" %)
172 (((
173 Flexisip SIP proxy server version >= 2.0 has support for all the push notification solutions described above.
174 )))
175
176 (% class="wikigeneratedid" %)
177 == Push integration in SDK > 5.0 ==
178
179 Several features have been added in the version 5.0 of the linphone SDK to make the integration of push notifications (voip & remote) easier for the application developper. If you wish to enable them, you can have a look here : [[Enabling 5.0 Push Management in SDK>>https://wiki.linphone.org/xwiki/wiki/public/view/Lib/Features/Liblinphone%205.0%20new%20features%20and%20how%20to%20use%20them/#HiOS]]
180
181 == CallKit integration ==
182
183 Starting from linphone-sdk >= 4.3, **Callkit** must be integrated in the following way:
184
185 * Add the **CallKit** framework into your application's dependencies in Xcode.
186 * Implement the **CXProviderDelegate** protocol within your **ApplicationDelegate**
187 * Add the configuration **"use_callkit=1"** in the section **"app" **or call [[**linphone_core_enable_callkit()**>>https://www.linphone.org/snapshots/docs/liblinphone/swift/Classes/Core.html#/s:10linphonesw4CoreC14callkitEnabledSbvp]] before the linphone core starts.
188 * **Your CallKit delegate** MUST inform the **LinphoneCore** when **AVAudioSession** is activated, as follows:
189
190 {{code language="swift"}}
191 func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
192 lc.activateAudioSession(actived: true)
193 }
194
195 func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
196 lc.activateAudioSession(actived: false)
197 }
198 {{/code}}
199
200 * Since linphone-sdk >= 4.5, **your CallKit delegate** MUST configure the **AVAudioSession **when a new call is incoming/outgoing, as follows:
201
202 (((
203 {{code language="swift"}}
204 func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
205 CallManager.instance().lc?.configureAudioSession()
206 // accept call here
207 action.fulfill()
208 }
209
210 func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
211 CallManager.instance().lc?.configureAudioSession()
212 // start an outgoing call
213 action.fulfill()
214 }
215 {{/code}}
216 )))
217
218 === Display an incoming call ===
219
220 {{code language="swift"}}
221 let update = CXCallUpdate()
222 update.remoteHandle = CXHandle(type:.generic, value: "Call incoming")
223 let uuid = UUID()
224 provider.reportNewIncomingCall(with: uuid, update: update) {error in}
225 {{/code}}
226
227 === Answer an incoming call ===
228
229 Since iOS 13, Apple requests **CallKit **to be invoked to display the incoming call immediately when a **PushKit** notification is received. So sometimes you can answer the **CallKit** before a **LinphoneCall** is received. In the callback **CXAnswerCallAction**, if a **LinphoneCall** has not yet been received, you need to configure your **AVAudioSession** and accept the call when you receive it. Otherwise, accept the call directly.
230
231 {{code language="swift"}}
232 func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
233 if (call == nil || call.state != Call.State.IncomingReceived) {
234 // configure audio session here. Use 48000 Hz as sampling rate.
235 } else {
236 // accept call here
237 call.acceptWithParams(params: callParams)
238 }
239 action.fulfill()
240 }
241 {{/code}}
242
243 === Terminate a call ===
244
245 {{code language="swift"}}
246 func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
247 // terminate call here
248 call.terminate()
249 action.fulfill()
250 }
251 {{/code}}
252
253 === Start an outgoing call ===
254
255 When starting an outgoing call from the application view, it must following these steps:
256
257 Before starting an outgoing call, make sure others calls are paused by callkit.
258
259 Then add these codes to your class when starting an outgoing call
260
261 {{code language="swift"}}
262 let handle = CXHandle(type: .generic, value: displayName)
263 let startCallAction = CXStartCallAction(call: uuid, handle: handle)
264 let transaction = CXTransaction(action: startCallAction)
265 let callController = CXCallController()
266 callController.request(_ transaction: transaction, completion: @escaping (Error?) -> Void)
267 {{/code}}
268
269 Then this callback will be called.
270
271 {{code language="swift"}}
272 func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
273 // start an outgoing call
274 lc.inviteAddressWithParams(addr: addr, params: params)
275 action.fulfill()
276 }
277
278 {{/code}}
279
280 To ensure the audio session works properly for this outgoing call.
281
282 {{code language="swift"}}
283 // When outgoing call is created
284 reportOutgoingCall(with UUID: UUID, startedConnectingAt dateStartedConnecting: Date?)
285 // When outgoing call is answered
286 reportOutgoingCall(with UUID: UUID, connectedAt dateConnected: Date?)
287
288
289 {{/code}}
290
291 === Hold/resume a call ===
292
293 Before resuming a call, make sure others calls are paused by callkit.
294
295 {{code language="swift"}}
296 func provider(_ provider: CXProvider, perform action: CXSetHeldCallAction) {
297 // If this is a conference, leave/enter the conference.
298 // Otherwide, pause/resume the call.
299 call.pause()
300 action.fulfill()
301 }
302
303 {{/code}}
304
305 === Mute/un-mute a call ===
306
307 {{code language="swift"}}
308 func provider(_ provider: CXProvider, perform action: CXSetMutedCallAction) {
309 // Mute/un-mute a call
310 lc.micEnabled = false
311 action.fulfill()
312 }
313
314 {{/code}}
315
316 === Play DTMF ===
317
318 {{code language="swift"}}
319 func provider(_ provider: CXProvider, perform action: CXPlayDTMFCallAction) {
320 // Send DTMF
321 call.sendDtmf(dtmf: digit)
322 action.fulfill()
323 }
324 {{/code}}
325
326 === Group calls ===
327
328 {{code language="swift"}}
329 func provider(_ provider: CXProvider, perform action: CXSetGroupCallAction) {
330 // add all to conference
331 lc.addAllToConference()
332 action.fulfill()
333 }
334 {{/code}}
335
336 === Transfer a call ===
337
338 Callkit does not support call transfer when Linphone does. If you wan to realise the call transfer with Callkit, you must follow these tips:
339
340 * For callkit, an unique uuid represents a call.
341 * For Linphone, the referred call will use a different callid than the original call.
342
343 Here is the integration of callkit in [[linphone-iphone/ProviderDelegate.swift>>https://gitlab.linphone.org/BC/public/linphone-iphone/blob/master/Classes/ProviderDelegate.swift]].
344
345 === Troubleshooting ===
346
347 ==== Distorted voice when using bluetooth devices ( using SDK 4.4.x) ====
348
349 Error log: **"Too many samples to drop, dropping entire frame."**
350
351 Solution: Add callback of **AVAudioSessionRouteChangeNotification** in your application, and call linphone_core_audio_route_changed(lc) in this callback. Here is the integration of Linphone [[linphone-iphone/LinphoneManager.m>>https://gitlab.linphone.org/BC/public/linphone-iphone/-/blob/release/4.3/Classes/LinphoneManager.m]].
352
353
354 == Technical solutions to advertise instant messages ==
355
356 The table below summarizes the possible options. Remember that using PushKit is no longer possible since iOS 13 / Xcode 11.
357
358 |=Use case|=Push notification type|=Solution
359 |Basic app, not using end to end encryption.|[[Remote Push Notification>>https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns]]|(((
360 The sender identity and the text content must be placed into the push notification sent by the server. The push notification is displayed to the user. When pressed, the app is resumed or launched, and can display the conversation related to the received notification.
361
362 Please note that the app has no way to perform any kind of pre-processing on the notification, such as perform deciphering of the message or fetching additional content (photos for example).
363 )))
364 |Advanced app, with security requirements.|[[Remote Push Notification>>https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns]] used together with a [[Notification Service Extension>>https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension]].|(((
365 Use [[Remote Push Notifications>>https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns]] handled by an app extension of type "[[Notification Service Extension>>https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension]]".
366
367 The app extension is bundled with the main app. It executes in a different process with restricted permissions, for example it cannot access geolocation information.
368
369 The Notification Service Extension will receive the remote push notification silently, in background. It has a constrained period of time to do some processing: connect to the SIP service, get the instant message, decipher it, and at the end update the notification to fill it with sender identity and clear text message. The notification is then displayed normally by iOS.
370
371 When pressed, the main application is launched and can display the conversation that relates to the received message. The app extension and the main app have a shared filesystem and messaging framework, with synchronisation mechanisms.
372
373 This solution is presented with details in the below section "Advertising instant messages with a Notification Service Extension". It is the one implemented in the Linphone application.
374 )))
375
376 === Advertising instant messages with a Notification Service Extension ===
377
378 This section describes a step by step procedure to implement state of art receiving of instant messages in a liblinphone based application, thanks to [[Notification Service Extension>>https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension]].
379
380 ==== Create the UNNotificationServiceExtension App Extension ====
381
382 A **Remote** push notification cannot resume an application to perform tasks in background. However it can do so with an app extension. An app extension is a process that is linked to the app but it doesn't share the same container (not the same process, not the same file system). The first step is then to create a UNNotificationServiceExtension.
383
384 Its goal is to catch the **Remote** push notification and modify the **user notification** before it is displayed. For this we need to connect to the server, get the new message then we can display the user notification.
385
386 In Xcode, in the “capabilities” menu, you must add the **App Group** capability for both the app and the app extension with the same App Group identifier: the //AppGroupId//. This identifier is used to reach the file system that is shared between the main App and the UNNotificationServiceExtension.
387
388 ==== Create a Shared Core in app ====
389
390 Since version 4.4, liblinphone has a new concept of **Shared Linphone Core** to be able to manage a LinphoneCore in both the app and the app extension. The goal of the Shared Cores is to be able to create several Cores at the same time with the same configuration while making sure that only one Shared Core can write to the configuration files and the databases at the same time.
391
392 There are two types of Shared Cores:
393 - The **Main Shared Core** is the Core owned by the application. It can stop the **Executor Shared Core** when it needs to start. It is the one that has the priority.
394 - The **Executor Shared Core** is the Core of the app extension. It can't start if another Shared Core is already running and it can be stopped by the **Main Shared Core **at any time.
395
396 The mutual exclusion between Shared Cores is handled by the liblinphone.
397
398 (% class="box infomessage" %)
399 (((
400 The liblinphone methods for creating the Shared Core exists in C and Swift. A newly written application will prefer to use Swift, while an already existing application written in Objective-C can use C.
401 )))
402
403 The Main Shared Core is to be created as follows:
404
405 1. Use// [[linphone_config_new_for_shared_core>>https://www.linphone.org/snapshots/docs/liblinphone/swift/Classes/Config.html#/s:10linphonesw6ConfigC16newForSharedCore10appGroupId14configFilename11factoryPathACSgSS_S2StFZ]](app_group_id, config_filename, factory_path)// taking your //AppGroupId// and a config filename (i.e. linphonerc). It computes the path in the shared memory for your config file. The factory config path works as for a normal LinphoneCore. It returns a **LinphoneConfig** object suitable to instantiate a Shared Core.
406 1. Use //[[linphone_factory_create_shared_core_with_config>>https://www.linphone.org/snapshots/docs/liblinphone/swift/Classes/Factory.html#/s:10linphonesw7FactoryC26createSharedCoreWithConfig6config13systemContext10appGroupId04mainE0AA0E0CAA0G0C_SvSgSSSbtKF]](factory, config, system_context, app_group_id, main_core)// to create the Shared Core. Set //main_core=TRUE// as we are creating a Main Shared Core for the app.
407
408 Note: linphone_factory_create_shared_core (factory, config_filename, factory_config_path, system_context, app_group_id, main_core) combines the two steps in a single function.
409
410 ==== Stop the Main Shared Core when going to background ====
411
412 The app extension will need to start an **Executor Shared Core** to get the new messages. To allow that, you need to stop the **Main Shared Core** each time the app goes in background. Reciprocally you need to start it again when the app goes to foreground.
413
414 * In //(void)applicationDidEnterBackground: (UIApplication *)application// : you need to call [[//linphone_core_stop//()>>https://www.linphone.org/snapshots/docs/liblinphone/swift/Classes/Core.html#/s:10linphonesw4CoreC4stopyyF]]
415 * In //(void)applicationWillEnterForeground: (UIApplication *)application// : you need to call [[linphone_core_start()>>https://www.linphone.org/snapshots/docs/liblinphone/swift/Classes/Core.html#/s:10linphonesw4CoreC5startyyKF]]
416
417 ==== Migrate all the configuration files to the shared file system (optional) ====
418
419 This section is applicable to apps using liblinphone before Xcode 11 arrived.
420
421 You have created a **Main Shared Core** instead of the usual **Core**. Now all the configuration files need to be moved to the **shared file system **in order to still have the SIP account information, the call logs, and the conversation history, etc.
422
423 For this we use these three functions:
424
425 - const char *linphone_factory_get_config_dir(LinphoneFactory *factory, void *context) that leads to /Library/Application Support/linphone/
426
427 - const char *linphone_factory_get_data_dir(LinphoneFactory *factory, void *context) that leads to /Library/Preferences/linphone/
428
429 - const char *linphone_factory_get_download_dir(LinphoneFactory *factory, void *context) that leads to /Library/Caches/
430
431 These functions return paths to the different iOS application configuration directories, depending on the context argument. If context = NULL, the returned path is in the application file system. If context = AppGroupId, the path leads to the file system shared between the app and the app extension.
432
433 ==== Set up the app extension to get the message ====
434
435 The function didReceive() of the **NotificationService** app extension is called when a **Remote** push notification is received. It has ~~30 seconds to get the message before the user notification is finally displayed by the system.
436
437 Please note that the push notification body must contain two string attributes (in its dictionary):
438
439 * call_id : the call_id of the SIP MESSAGE carrying the IM, when the push notification is related to a message.
440 * chat_room_addr : the SIP address of a chatroom in which the user is being INVITEd, when the push notification is related to an INVITE to join a user to chat room.
441
442 These are strong requirements. Flexisip proxy server of course takes care of adding these attributes since version 2.0.
443
444 An **Executor Shared Linphone Core** is required to retrieve the message. It is created as in step 2 but by setting main_core=FALSE. The **main shared core** running in the main application can stop the **Executor Shared Core** when the user puts the application in foreground.
445
446 These two methods are useful to perform the tasks of the app extension:
447
448 - [[LinphonePushNotificationMessage *linphone_core_get_new_message_from_callid(lc, call_id)>>https://www.linphone.org/snapshots/docs/liblinphone/swift/Classes/Core.html#/s:10linphonesw4CoreC23getNewMessageFromCallid6callIdAA016PushNotificationE0CSgSS_tF]] : to get the message from the //call_id// attribute embedded in the push notification payload.
449
450 - [[LinphoneChatRoom *linphone_core_get_new_chat_room_from_conf_addr(lc , chat_room_addr)>>https://www.linphone.org/snapshots/docs/liblinphone/swift/Classes/Core.html#/s:10linphonesw4CoreC26getNewChatRoomFromConfAddr04chatfI0AA0eF0CSgSS_tF]] : to get the new chat room from the //chat_room_addr// attribute embedded in the push notification. The app extension can use this information to indicate to the user that has been invited into a new chat room.
451
452 (% class="box infomessage" %)
453 (((
454 Don't call linphone_core_start() yourself. The above two functions will start the Shared Core if needed.
455 )))
456
457 Once ever of the two functions has returned, linphone_core_stop() must be called, in order to allow the core to perform additional actions that usually follow the receiving of a message, such as sending a delivery notification (IMDN), and finally release the shared core lock, to let other push notification to be processed by other notification service extension instances.
458
459 (% class="box infomessage" %)
460 (((
461 iOS launches a new instance of the app extension for every push notification received. Proper synchronisation between these multiple instances and the main shared core is performed by liblinphone internally.
462 )))
463
464 These two methods used by the app extension work when the main application is in background or in foreground. This means that the main application does not need to manage incoming messages. **The app extension will take in charge the notification of ALL the incoming messages to the user.**
465
466 If the application existed before XCode 11, it was probably user local notification to show IMs: this code needs to be removed now that the app extension is handling incoming IMs.
467
468 ==== Adding actions in user notifications: UNNotificationContentExtension ====
469
470 Linphone also uses the UNNotificationContentExtension app extension in addition of the UNNotificationServiceExtension, in order to implement the **reply** and **mark as seen** buttons.
471
472 The user notifications displayed by the NotificationService extension need a NotificationContent extension to add a **NotificationCategory **as well as some **actions** attached to this category. The categories and actions declared in the main app won't work when the app is in background.
473
474 If the app is in foreground, the NotificationContent extension won't be able to start a Shared Core so the app will need to handle the actions.
475
476 To summarize, the notification categories and attached actions must be declared in both the NotificationContent extension and the main app, despite the Notification Service Extension is centralizing the incoming push notifications and the display of the IM.
477
478 ==== Update Contact URI parameters ====
479
480 In order to get push notifications, the iOS app must send its push token(s) to the SIP server.
481
482 These push paramers are sent in the Contact URI parameter in the REGISTER.
483
484 We recommend the syntax and principles of [[RFC8599 - Push Notification with the Session Initiation Protocol>>https://tools.ietf.org/html/rfc8599]], on top of which we had unfortunately to plug extension to cover the specificities of iOS since version 13, because the app will actually need two different push notification tokens (one for Callkit, one for Remote Notifications).
485
486 The extensions we made are summarized by this ABNF grammar:
487
488 * "pn-prid=“ token [ “:” service ] *( “&” token “:” service )
489 * "pn-param=" TeamId ”.” BundleId ”.” service *( “&” service )
490 * "pn-provider=apns"
491 * service = "voip" / "remote"
492 * token = <voip push token or remote push token>
493
494 Example with voip and remote push token:
495
496 * pn-prid=00fc13adff78512:voip&c11292f7b74733d:remote
497 * pn-param=DEF123GHIJ.org.linphone.phone.voip&remote
498 * pn-provider=apns
499
500 Example only with remote push token:
501
502 * pn-prid=c11292f7b74733d:remote
503 * pn-param=DEF123GHIJ.org.linphone.phone.remote
504 * pn-provider=apns
505
506 The "voip" service stands for PushKit kind of notifications, while the "remote" service is for the basic "Remote Notification" system.
507
508 These parameters must be added at application to the ProxyConfig object using [[//linphone_proxy_config_set_contact_uri_parameters//()>>https://www.linphone.org/snapshots/docs/liblinphone/swift/Classes/ProxyConfig.html#/s:10linphonesw11ProxyConfigC20contactUriParametersSSvp]].
509
510 ==== Bugs ====
511
512 It appears that in iOS < 12, if the UNNotificationServiceExtension takes more than 1 second to start, it is killed by the system. Once it has successfully started once, the process is kept in cache and works every time. It is removed from the cache after ~~30 minutes without any push notification.
513
514 When the app extension fails to start, the push notification can't be caught to retrieve the message. We used the "loc-key" argument of the push notification JSON payload to put a key. This key is an entry in our translation files. So, when the app extension fails to start, we will display a localized message similar to "You have received a new message".
515
516 This limitation is not documented by Apple and we haven't been able to reproduce it in iOS versions >= 12.
517
518 ==== Beyond the scene ====
519
520 [[This page>>doc:.Shared cores.WebHome]] describes the internal mechanisms used by liblinphone for Shared Core synchronisation.
521
522 = Handling liblinphone log =
523
524 In order to see liblinphone logs in your IOS app (for example in your Xcode console) follow these steps :
525
526 Put in your code at the launching of the app :
527
528 {{code language="Objective-C"}}
529 linphone_core_set_log_handler(your_log_handler);
530 {{/code}}
531
532 This will make the liblinphone logs to call your_log_handler and so be processed as a log from your app.
533
534 You can set the liblinphone log level by using the functions documented [[here>>http://linphone.org/docs/liblinphone/group__initializing.html#ga685b79d92af0184dbeac46df14bf4705]].
535
536 == IOS log handler for liblinphone ==
537
538 Once you have set your log handler, you need to process liblinphone log in order to incorporate them into your app logs.
539
540 Here is a short example of how to manage liblinphone log into an IOS app :
541
542 {{code language="Objective-C"}}
543 void linphone_iphone_log_handler(const char *domain, OrtpLogLevel lev, const char *fmt, va_list args) {
544 NSString *format = [[NSString alloc] initWithUTF8String:fmt];
545 NSString *formatedString = [[NSString alloc] initWithFormat:format arguments:args];
546 NSString *lvl;
547
548 if (!domain)
549 domain = "lib";
550 // since \r are interpreted like \n, avoid double new lines when logging network packets (belle-sip)
551 // output format is like: I/ios/some logs. We truncate domain to **exactly** DOMAIN_SIZE characters to have
552 // fixed-length aligned logs
553 switch (lev) {
554 case ORTP_FATAL:
555 lvl = @"Fatal";
556 break;
557 case ORTP_ERROR:
558 lvl = @"Error";
559 break;
560 case ORTP_WARNING:
561 lvl = @"Warning";
562 break;
563 case ORTP_MESSAGE:
564 lvl = @"Message";
565 break;
566 case ORTP_DEBUG:
567 lvl = @"Debug";
568 break;
569 case ORTP_TRACE:
570 lvl = @"Trace";
571 break;
572 case ORTP_LOGLEV_END:
573 return;
574 }
575 if ([formatedString containsString:@"\n"]) {
576 NSArray *myWords = [[formatedString stringByReplacingOccurrencesOfString:@"\r\n" withString:@"\n"]
577 componentsSeparatedByString:@"\n"];
578 for (int i = 0; i < myWords.count; i++) {
579 NSString *tab = i > 0 ? @"\t" : @"";
580 if (((NSString *)myWords[i]).length > 0) {
581 NSLog(@"[%@] %@%@", lvl, tab, (NSString *)myWords[i]);
582 }
583 }
584 } else {
585 NSLog(@"[%@] %@", lvl, [formatedString stringByReplacingOccurrencesOfString:@"\r\n" withString:@"\n"]);
586 }
587 }
588 {{/code}}
589
590
591
592 )))
593
594 (% class="col-xs-12 col-sm-4" %)
595 (((
596 {{box title="**Contents**"}}
597 {{toc/}}
598 {{/box}}
599 )))
600 )))