From d94f5beeff0afa8bdb4634ddb08da3e873054030 Mon Sep 17 00:00:00 2001 From: Oliver Zimmerman Date: Fri, 13 Dec 2024 17:03:57 +0000 Subject: [PATCH] chore: adjust docs so that notification content is in correct place. Update actual package readme --- README.md | 31 +-- docs-markdown/classes/Call.md | 17 -- packages/telnyx_webrtc/README.md | 432 ++++++++++++++++++++++--------- 3 files changed, 322 insertions(+), 158 deletions(-) diff --git a/README.md b/README.md index cc55ca6..a0b93c1 100644 --- a/README.md +++ b/README.md @@ -180,23 +180,6 @@ In order to end a call, we can get a stored instance of Call and call the .endCa } ``` -### Handling Late Notifications -If notifcations arrive very late due to no internet connectivity, It is good to always flag it as a missed call. You can do that using the -code snippet below : - -```dart -const CALL_MISSED_TIMEOUT = 60; - - DateTime nowTime = DateTime.now(); - Duration? difference = nowTime?.difference(message.sentTime!); - - if (difference.inSeconds > CALL_MISSED_TIMEOUT) { - NotificationService.showMissedCallNotification(message); - return; -} -``` - - ### DTMF (Dual Tone Multi Frequency) In order to send a DTMF message while on a call you can call the .dtmf(callID, tone), method where tone is a String value of the character you would like pressed: @@ -476,7 +459,21 @@ For a detailed tutorial, please visit our official [Push Notification Docs](http }); ``` +### Handling Late Notifications +If notifications arrive very late due to no internet connectivity, It is good to always flag it as a missed call. You can do that using the +code snippet below : + +```dart +const CALL_MISSED_TIMEOUT = 60; + + DateTime nowTime = DateTime.now(); + Duration? difference = nowTime?.difference(message.sentTime!); + if (difference.inSeconds > CALL_MISSED_TIMEOUT) { + NotificationService.showMissedCallNotification(message); + return; +} +``` #### Best Practices for Push Notifications on iOS 1. Push Notifications only work in foreground for apps that are run in `debug` mode (You will not receive push notifications when you terminate the app while running in debug mode). Make sure you are in `release` mode. Preferably test using Testfight or Appstore. diff --git a/docs-markdown/classes/Call.md b/docs-markdown/classes/Call.md index 2c30903..6e4bc30 100644 --- a/docs-markdown/classes/Call.md +++ b/docs-markdown/classes/Call.md @@ -21,23 +21,6 @@ In order to end a call, we can get a stored instance of Call and call the .endCa } ``` -### Handling Late Notifications -If notifcations arrive very late due to no internet connectivity, It is good to always flag it as a missed call. You can do that using the -code snippet below : - -```dart -const CALL_MISSED_TIMEOUT = 60; - - DateTime nowTime = DateTime.now(); - Duration? difference = nowTime?.difference(message.sentTime!); - - if (difference.inSeconds > CALL_MISSED_TIMEOUT) { - NotificationService.showMissedCallNotification(message); - return; -} -``` - - ### DTMF (Dual Tone Multi Frequency) In order to send a DTMF message while on a call you can call the .dtmf(callID, tone), method where tone is a String value of the character you would like pressed: diff --git a/packages/telnyx_webrtc/README.md b/packages/telnyx_webrtc/README.md index f2b1d2b..605ca60 100644 --- a/packages/telnyx_webrtc/README.md +++ b/packages/telnyx_webrtc/README.md @@ -3,7 +3,6 @@ # Telnyx Flutter Voice SDK - Enable Telnyx real-time communication services on Flutter applications (Android / iOS / Web) :telephone_receiver: :fire: ## Features @@ -45,45 +44,51 @@ on the iOS platform, you need to add the microphone permission to your Info.plis $(PRODUCT_NAME) Microphone Usage! ``` +## Basic Usage + ### Telnyx Client TelnyxClient() is the core class of the SDK, and can be used to connect to our backend socket connection, create calls, check state and disconnect, etc. -Once an instance is created, you can call the .connect() method to connect to the socket. An error will appear as a socket response if there is no network available: +Once an instance is created, you can call the .connect() method to connect to the socket with either a token or credentials (see below). An error will appear as a socket response if there is no network available: ```dart TelnyxClient _telnyxClient = TelnyxClient(); - _telnyxClient.connect(); ``` ### Logging into Telnyx Client -To log into the Telnyx WebRTC client, you'll need to authenticate using a Telnyx SIP Connection. Follow our [quickstart guide](https://developers.telnyx.com/docs/v2/webrtc/quickstart) to create **JWTs** (JSON Web Tokens) to authenticate. To log in with a token we use the tokinLogin() method. You can also authenticate directly with the SIP Connection `username` and `password` with the credentialLogin() method: +To log into the Telnyx WebRTC client, you'll need to authenticate using a Telnyx SIP Connection. Follow our [quickstart guide](https://developers.telnyx.com/docs/v2/webrtc/quickstart) to create **JWTs** (JSON Web Tokens) to authenticate. To log in with a token we use the connectWithToken() method. You can also authenticate directly with the SIP Connection `username` and `password` with the connectWithCredential() method: ```dart - _telnyxClient.tokenLogin(tokenConfig) + _telnyxClient.connectWithToken(tokenConfig) //OR - _telnyxClient.credentialLogin(credentialConfig) + _telnyxClient.connectWithCredential(credentialConfig) ``` -**Note:** **tokenConfig** and **credentialConfig** are simple classes that represent login settings for the client to use. They look like this: +**Note:** **tokenConfig** and **credentialConfig** are simple classes that represent login settings for the client to use they extend a base Config class with shared properties. They look like this: ```dart - /// Creates an instance of CredentialConfig which can be used to log in +/// Creates an instance of CredentialConfig which can be used to log in /// /// Uses the [sipUser] and [sipPassword] fields to log in /// [sipCallerIDName] and [sipCallerIDNumber] will be the Name and Number associated /// [notificationToken] is the token used to register the device for notifications if required (FCM or APNS) /// The [autoReconnect] flag decided whether or not to attempt a reconnect (3 attempts) in the case of a login failure with /// legitimate credentials -class CredentialConfig { - CredentialConfig(this.sipUser, this.sipPassword, this.sipCallerIDName, - this.sipCallerIDNumber, this.notificationToken, this.autoReconnect); - - final String sipUser; - final String sipPassword; - final String sipCallerIDName; - final String sipCallerIDNumber; - final String? notificationToken; - final bool? autoReconnect; +class CredentialConfig extends Config { + CredentialConfig({ + required this.sipUser, + required this.sipPassword, + required super.sipCallerIDName, + required super.sipCallerIDNumber, + super.notificationToken, + super.autoReconnect, + required super.debug, + super.ringTonePath, + super.ringbackPath, + }); + + final String sipUser; + final String sipPassword; } /// Creates an instance of TokenConfig which can be used to log in @@ -93,112 +98,21 @@ class CredentialConfig { /// [notificationToken] is the token used to register the device for notifications if required (FCM or APNS) /// The [autoReconnect] flag decided whether or not to attempt a reconnect (3 attempts) in the case of a login failure with /// a legitimate token -class TokenConfig { - TokenConfig(this.sipToken, this.sipCallerIDName, this.sipCallerIDNumber, - this.notificationToken, this.autoReconnect); - - final String sipToken; - final String sipCallerIDName; - final String sipCallerIDNumber; - final String? notificationToken; - final bool? autoReconnect; -} - ``` - -#### Adding push notifications - Android platform -The Android platform makes use of Firebase Cloud Messaging in order to deliver push notifications. If you would like to receive notifications when receiving calls on your Android mobile device you will have to enable Firebase Cloud Messaging within your application. -For a detailed tutorial, please visit our official [Push Notification Docs](https://developers.telnyx.com/docs/v2/webrtc/push-notifications?type=Android) -1. Add the `metadata` to CallKitParams `extra` field -```dart - - static Future showNotification(RemoteMessage message) { - CallKitParams callKitParams = CallKitParams( - android:..., - ios:..., - extra: message.data, - ) - await FlutterCallkitIncoming.showCallkitIncoming(callKitParams); - } -``` - -2. Listen for Call Events and invoke the `handlePushNotification` method -```dart - FlutterCallkitIncoming.onEvent.listen((CallEvent? event) { - switch (event!.event) { - case Event.actionCallIncoming: - // retrieve the push metadata from extras - PushMetaData? pushMetaData = PushMetaData.fromJson( - jsonDecode(event.body['extra']['metadata'])); - _telnyxClient.handlePushNotification(pushMetaData, credentialConfig, tokenConfig); - break; - case Event.actionCallStart: - .... - break; - case Event.actionCallAccept: - ... - logger.i('Call Accepted Attach Call'); - break; - }); -``` - - - -#### Adding push notifications - iOS platform -The iOS Platform makes use of the Apple Push Notification Service (APNS) and Pushkit in order to deliver and receive push notifications -For a detailed tutorial, please visit our official [Push Notification Docs](https://developers.telnyx.com/docs/v2/webrtc/push-notifications?lang=ios) - -1. Listen for incoming calls in AppDelegate.swift class -```swift - func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) { - print("didReceiveIncomingPushWith") - guard type == .voIP else { return } - - if let metadata = payload.dictionaryPayload["metadata"] as? [String: Any] { - var callID = UUID.init().uuidString - if let newCallId = (metadata["call_id"] as? String), - !newCallId.isEmpty { - callID = newCallId - } - let callerName = (metadata["caller_name"] as? String) ?? "" - let callerNumber = (metadata["caller_number"] as? String) ?? "" - - let id = payload.dictionaryPayload["call_id"] as? String ?? UUID().uuidString - let isVideo = payload.dictionaryPayload["isVideo"] as? Bool ?? false - - let data = flutter_callkit_incoming.Data(id: id, nameCaller: callerName, handle: callerNumber, type: isVideo ? 1 : 0) - data.extra = payload.dictionaryPayload as NSDictionary - data.normalHandle = 1 - - let caller = callerName.isEmpty ? (callerNumber.isEmpty ? "Unknown" : callerNumber) : callerName - let uuid = UUID(uuidString: callID) - - //set more data - //data.iconName = ... - //data..... - SwiftFlutterCallkitIncomingPlugin.sharedInstance?.showCallkitIncoming(data, fromPushKit: true) - } - } -``` - -2. Listen for Call Events and invoke the `handlePushNotification` method -```dart - FlutterCallkitIncoming.onEvent.listen((CallEvent? event) { - switch (event!.event) { - case Event.actionCallIncoming: - // retrieve the push metadata from extras - PushMetaData? pushMetaData = PushMetaData.fromJson(event.body['extra']['metadata']); - _telnyxClient.handlePushNotification(pushMetaData, credentialConfig, tokenConfig); - break; - case Event.actionCallStart: - .... - break; - case Event.actionCallAccept: - ... - logger.i('Call Accepted Attach Call'); - break; +class TokenConfig extends Config { + TokenConfig({ + required this.sipToken, + required super.sipCallerIDName, + required super.sipCallerIDNumber, + super.notificationToken, + super.autoReconnect, + required super.debug, + super.ringTonePath, + super.ringbackPath, }); -``` + final String sipToken; +} + ``` ### Creating a call invitation In order to make a call invitation, we first create an instance of the Call class with the .call instance. This creates a Call class which can be used to interact with calls (invite, accept, decline, etc). @@ -231,8 +145,9 @@ _telnyxClient.onSocketMessageReceived = (TelnyxMessage message) { { // Handle an invitation Update UI or Navigate to new screen, etc. // Then, through an answer button of some kind we can accept the call with: + // This will return an instance of the Call class which can be used to interact with the call or monitor it's state. _incomingInvite = message.message.inviteParams; - _telnyxClient.createCall().acceptCall( + _call = _telnyxClient.acceptCall( _incomingInvite, "callerName", "000000000", "State"); break; } @@ -247,7 +162,6 @@ _telnyxClient.onSocketMessageReceived = (TelnyxMessage message) { break; } } - notifyListeners(); }; ``` @@ -297,8 +211,278 @@ To put a call on hold, you can simply call the .onHoldUnholdPressed() method: _telnyxClient.call.onHoldUnholdPressed(); ``` +## Advanced Usage - Push Notifications + +### Adding push notifications - Android platform +The Android platform makes use of Firebase Cloud Messaging in order to deliver push notifications. To receive notifications when receiving calls on your Android mobile device you will have to enable Firebase Cloud Messaging within your application. +For a detailed tutorial, please visit our official [Push Notification Docs](https://developers.telnyx.com/docs/v2/webrtc/push-notifications?type=Android). +The Demo app uses the [FlutterCallkitIncoming](https://pub.dev/packages/flutter_callkit_incoming) plugin to show incoming calls. To show a notification when receiving a call, you can follow the steps below: +1. Listen for Background Push Notifications, Implement the `FirebaseMessaging.onBackgroundMessage` method in your `main` method +```dart + +@pragma('vm:entry-point') +Future main() async { + WidgetsFlutterBinding.ensureInitialized(); + + if (defaultTargetPlatform == TargetPlatform.android) { + // Android Only - Push Notifications + await Firebase.initializeApp(); + FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler); + + await FirebaseMessaging.instance + .setForegroundNotificationPresentationOptions( + alert: true, + badge: true, + sound: true, + ); + } + runApp(const MyApp()); +} +``` + +2. Optionally Add the `metadata` to CallKitParams `extra` field +```dart + + static Future showNotification(RemoteMessage message) { + CallKitParams callKitParams = CallKitParams( + android:..., + ios:..., + extra: message.data, + ) + await FlutterCallkitIncoming.showCallkitIncoming(callKitParams); + } +``` + + +3. Handle the push notification in the `_firebaseMessagingBackgroundHandler` method +```dart + +Future _firebaseMessagingBackgroundHandler(RemoteMessage message) async { + //show notifcation + showNotification(message); + + //Listen to action from FlutterCallkitIncoming + FlutterCallkitIncoming.onEvent.listen((CallEvent? event) async { + switch (event!.event) { + case Event.actionCallAccept: + // Set the telnyx metadata for access when the app comes to foreground + TelnyxClient.setPushMetaData( + message.data, isAnswer: true, isDecline: false); + break; + case Event.actionCallDecline: + /* + * When the user declines the call from the push notification, the app will no longer be visible, and we have to + * handle the endCall user here. + * Login to the TelnyxClient and end the call + * */ + ... + }}); +} + + +``` + +4. Use the `TelnyxClient.getPushMetaData()` method to retrieve the metadata when the app comes to the foreground. This data is only available on 1st access and becomes `null` afterward. +```dart + Future _handlePushNotification() async { + final data = await TelnyxClient.getPushMetaData(); + PushMetaData? pushMetaData = PushMetaData.fromJson(data); + if (pushMetaData != null) { + _telnyxClient.handlePushNotification(pushMetaData, credentialConfig, tokenConfig); + } + } +``` + +5. To Handle push calls on foreground, Listen for Call Events and invoke the `handlePushNotification` method +```dart +FlutterCallkitIncoming.onEvent.listen((CallEvent? event) { + switch (event!.event) { + case Event.actionCallIncoming: + // retrieve the push metadata from extras + final data = await TelnyxClient.getPushData(); + ... + _telnyxClient.handlePushNotification(pushMetaData, credentialConfig, tokenConfig); + break; + case Event.actionCallStart: + .... + break; + case Event.actionCallAccept: + ... + logger.i('Call Accepted Attach Call'); + break; + }); +``` + +#### Best Practices for Push Notifications on Android +1. Request for Notification Permissions for android 13+ devices to show push notifications. More information can be found [here](https://developer.android.com/develop/ui/views/notifications/notification-permission) +2. Push Notifications only work in foreground for apps that are run in `debug` mode (You will not receive push notifications when you terminate the app while running in debug mode). +3. On Foreground calls, you can use the `FirebaseMessaging.onMessage.listen` method to listen for incoming calls and show a notification. +```dart + FirebaseMessaging.onMessage.listen((RemoteMessage message) { + TelnyxClient.setPushMetaData(message.data); + NotificationService.showNotification(message); + mainViewModel.callFromPush = true; + }); +``` +4. To handle push notifications on the background, use the `FirebaseMessaging.onBackgroundMessage` method to listen for incoming calls and show a notification and make sure to set the ` TelnyxClient.setPushMetaData` when user answers the call. +```dart + TelnyxClient.setPushMetaData( + message.data, isAnswer: true, isDecline: false); +``` +5. When you call the `telnyxClient.handlePushNotification` it connects to the `telnyxClient`, make sure not to call the `telnyxClient.connect()` method after this. e.g an Edge case might be if you call `telnyxClient.connect()` on Widget `init` method it + will always call the `connect` method + + +6. Early Answer/Decline : Users may answer/decline the call too early before a socket connection is established. To handle this situation, + assert if the `IncomingInviteParams` is not null and only accept/decline if this is availalble. +```dart +bool waitingForInvite = false; + +void accept() { + +if (_incomingInvite != null) { + // accept the call if the incomingInvite arrives on time + _currentCall = _telnyxClient.acceptCall( + _incomingInvite!, _localName, _localNumber, "State"); + } else { + // set waitingForInvite to true if we have an early accept + waitingForInvite = true; + } +} + + + _telnyxClient.onSocketMessageReceived = (TelnyxMessage message) { + switch (message.socketMethod) { + ... + case SocketMethod.INVITE: + { + if (callFromPush) { + // For early accept of call + if (waitingForInvite) { + //accept the call + accept(); + waitingForInvite = false; + } + callFromPush = false; + } + + } + ... + } + } +``` + + + +### Adding push notifications - iOS platform +The iOS Platform makes use of the Apple Push Notification Service (APNS) and Pushkit in order to deliver and receive push notifications +For a detailed tutorial, please visit our official [Push Notification Docs](https://developers.telnyx.com/docs/v2/webrtc/push-notifications?lang=ios) +1. Register/Invalidate the push device token for iOS +```swift + func pushRegistry(_ registry: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) { + print(credentials.token) + let deviceToken = credentials.token.map { String(format: "%02x", $0) }.joined() + //Save deviceToken to your server + SwiftFlutterCallkitIncomingPlugin.sharedInstance?.setDevicePushTokenVoIP(deviceToken) + } + + func pushRegistry(_ registry: PKPushRegistry, didInvalidatePushTokenFor type: PKPushType) { + SwiftFlutterCallkitIncomingPlugin.sharedInstance?.setDevicePushTokenVoIP("") + } +``` + +2. For foreground calls to work, you need to register with callkit on the restorationHandler delegate function. You can also choose to register with callkit using iOS official documentation on + [CallKit](https://developer.apple.com/documentation/callkit/). +```swift + override func application(_ application: UIApplication, + continue userActivity: NSUserActivity, + restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool { + + let nameCaller = handleObj.getDecryptHandle()["nameCaller"] as? String ?? "" + let handle = handleObj.getDecryptHandle()["handle"] as? String ?? "" + let data = flutter_callkit_incoming.Data(id: UUID().uuidString, nameCaller: nameCaller, handle: handle, type: isVideo ? 1 : 0) + //set more data... + data.nameCaller = "dummy" + SwiftFlutterCallkitIncomingPlugin.sharedInstance?.startCall(data, fromPushKit: true) + + } +``` +3. Listen for incoming calls in AppDelegate.swift class +```swift + func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) { + print("didReceiveIncomingPushWith") + guard type == .voIP else { return } + + if let metadata = payload.dictionaryPayload["metadata"] as? [String: Any] { + var callID = UUID.init().uuidString + if let newCallId = (metadata["call_id"] as? String), + !newCallId.isEmpty { + callID = newCallId + } + let callerName = (metadata["caller_name"] as? String) ?? "" + let callerNumber = (metadata["caller_number"] as? String) ?? "" + + let id = payload.dictionaryPayload["call_id"] as? String ?? UUID().uuidString + + let data = flutter_callkit_incoming.Data(id: id, nameCaller: callerName, handle: callerNumber, type: isVideo ? 1 : 0) + data.extra = payload.dictionaryPayload as NSDictionary + data.normalHandle = 1 + + let caller = callerName.isEmpty ? (callerNumber.isEmpty ? "Unknown" : callerNumber) : callerName + let uuid = UUID(uuidString: callID) + + data.uuid = uuid!.uuidString + data.nameCaller = caller + + SwiftFlutterCallkitIncomingPlugin.sharedInstance?.showCallkitIncoming(data, fromPushKit: true) + } + } +``` + +4. Listen for Call Events and invoke the `handlePushNotification` method +```dart + FlutterCallkitIncoming.onEvent.listen((CallEvent? event) { + switch (event!.event) { + case Event.actionCallIncoming: + // retrieve the push metadata from extras + PushMetaData? pushMetaData = PushMetaData.fromJson(event.body['extra']['metadata']); + _telnyxClient.handlePushNotification(pushMetaData, credentialConfig, tokenConfig); + break; + case Event.actionCallStart: + .... + break; + case Event.actionCallAccept: + ... + logger.i('Call Accepted Attach Call'); + break; + }); +``` + +### Handling Late Notifications +If notifications arrive very late due to no internet connectivity, It is good to always flag it as a missed call. You can do that using the +code snippet below : + +```dart +const CALL_MISSED_TIMEOUT = 60; + + DateTime nowTime = DateTime.now(); + Duration? difference = nowTime?.difference(message.sentTime!); + + if (difference.inSeconds > CALL_MISSED_TIMEOUT) { + NotificationService.showMissedCallNotification(message); + return; +} +``` + + +#### Best Practices for Push Notifications on iOS +1. Push Notifications only work in foreground for apps that are run in `debug` mode (You will not receive push notifications when you terminate the app while running in debug mode). Make sure you are in `release` mode. Preferably test using Testfight or Appstore. + To test if push notifications are working, disconnect the telnyx client (while app is in foreground) and make a call to the device. You should receive a push notification. + + Questions? Comments? Building something rad? [Join our Slack channel](https://joinslack.telnyx.com/) and share. ## License [`MIT Licence`](./LICENSE) © [Telnyx](https://github.com/team-telnyx) +