SINClient Protocol Reference

Conforms to NSObject
Declared in SINClient.h

Overview

The SINClient is the Sinch SDK entry point.

It provides access to the feature classes in the Sinch SDK: SINCallClient and SINAudioController. It is also used to configure the user’s and device’s capabilities.

User Identification

The user IDs that are used to identify users application specific. If the app already has a scheme for user IDs (email addresses, phone numbers, customer numbers, etc.), the same ID could be used when configuring the SINClient.

Example

// Instantiate a client object using the client factory.
id<SINClient> sinchClient = [Sinch clientWithApplicationKey:@"<APPKEY>"
                                          applicationSecret:@"<APPSECRET>"
                                            environmentHost:@"clientapi.sinch.com"
                                                     userId:@"<USERID>"];

// Specify the client capabilities. At least one of the messaging or calling capabilities should be enabled.
[sinchClient setSupportCalling:YES];
[sinchClient setSupportPushNotifications:YES]; // (optional)

// Set your delegate object
sinchClient.delegate = ... ;

// Start the client
[sinchClient start];

// Start listening for incoming events (calls and messages).
[sinchClient startListeningOnActiveConnection];

// Use the SINCallClient to place and receive calls.

// Stop listening for incoming events (calls and messages).
[sinchClient stopListeningOnActiveConnection];

// Terminate the client when the calling and messaging functionalities are no longer needed.
[sinchClient terminate];

  delegate required method

The object that acts as the delegate of the receiving client.

@property (nonatomic, weak) id<SINClientDelegate> delegate

Discussion

The delegate object handles call state change events and must adopt the SINClientDelegate protocol.

Declared In

SINClient.h

  userId required method

ID of the local user

@property (nonatomic, readonly, copy) NSString *userId

Declared In

SINClient.h

– setSupportCalling: required method

Specify whether this device should support making and receiving calls. Default is NO.

- (void)setSupportCalling:(BOOL)supported

Parameters

supported

Enable or disable support making and receiving calls.

Discussion

Method should be called before calling [SINClient start].

See Also

Declared In

SINClient.h

– setDataProtectionType: required method

Specify the data protection type (NSFileProtectionType) for the files created and used by the Sinch SDK. If not set specifically, the files will inherit the data protection level defined in your Application.

- (void)setDataProtectionType:(NSFileProtectionType)type

Parameters

type

the data protection type applied to the files created by the Sinch SDK.

Discussion

Method should be called before calling [SINClient start].

Declared In

SINClient.h

– setSupportPushNotifications: required method

Specify whether this device should receive incoming calls via push notifications.

- (void)setSupportPushNotifications:(BOOL)supported

Parameters

supported

Enable or disable support for push notifications.

Discussion

Method should be called before calling [SINClient start].

Declared In

SINClient.h

– enableManagedPushNotifications required method

Specify that the Sinch SDK and platform should take care of sending the push notification to the other device via the appropriate push notification gateway (i.e. Apple Push Notification Service for iOS devices, and Firebase Cloud Messaging (FCM) for Android devices).

- (void)enableManagedPushNotifications

Discussion

(This require that you have uploaded your Apple Push Notification Certificate(s) on the Sinch website)

This method will internally also invoke [SINClient setSupportPushNotifications:YES]

Method should be called before calling [SINClient start].

Declared In

SINClient.h

– start required method

Start client to enable the calling functionality.

- (void)start

Discussion

The client delegate should be set before calling the start method to guarantee that delegate callbacks are received as expected.

Declared In

SINClient.h

– terminate required method

Terminate client when the calling functionality is no longer needed.

- (void)terminate

Discussion

It is generally recommended to initiate the Sinch client, start it, but not terminate it, during the lifetime of the running application. If incoming calls are not desired for a limited period of time or similar scenarios, it is instead recommended to only stop listening for incoming calls via the method ([SINClient stopListeningOnActiveConnection]). This is simply because initializing and starting the client is relatively resource intensive both in terms of CPU, as well as there is potentially network requests involved in stopping and re-starting the client.

If desired to dispose the client, it is required to explicitly invoke terminate (or terminateGracefully) to relinquish certain resources. This method should always be called before the application code releases its last reference to the client.

Declared In

SINClient.h

– terminateGracefully required method

Terminates the client, while still leaving it some time to finish up currently pending tasks, for example finishing pending HTTP requests.

- (void)terminateGracefully

Discussion

See [SINClient terminate].

Declared In

SINClient.h

– stop required method

THIS METHOD IS DEPRECATED. See [SINClient terminate]

- (void)stop

Declared In

SINClient.h

– isStarted required method

Check whether client is successfully started.

- (BOOL)isStarted

Return Value

A boolean value indicating whether the client has successfully started and is ready to perform calling functionality.

Declared In

SINClient.h

– startListeningOnActiveConnection required method

This will establish an active keep-alive connection as a signaling channel for receiving incoming calls.

- (void)startListeningOnActiveConnection

Discussion

Note that the active connection will only be kept open while the application is running in foreground. To support receiving calls while the application is in the background (or not running), please use push notifications.

Declared In

SINClient.h

– stopListeningOnActiveConnection required method

This will close the connection that is kept alive and used as signaling channel for receiving incoming calls. This method should be used when the application no longer intends to utilize the long-lived connection for receiving incoming calls.

- (void)stopListeningOnActiveConnection

Discussion

If the intention is to completely turn off incoming calls and the application is also using push notifications as a method of receiving incoming calls, then the application should also unregister previously registered push notification data via the method [SINClient unregisterPushNotificationDeviceToken] and/or [SINClient unregisterPushNotificationData].

Declared In

SINClient.h

– relayRemotePushNotificationPayload: required method

Method used to forward the Sinch-specific payload extracted from an incoming Apple Push Notification.

- (id<SINNotificationResult>)relayRemotePushNotificationPayload:(NSString *)payload

Parameters

payload

Sinch-specific payload which was transferred with an Apple Push Notification.

Return Value

Value indicating initial inspection of push notification payload.

Declared In

SINClient.h

– relayRemotePushNotification: required method

Method used to forward a remote notification dictionary if using [SINClient enableManagedPushNotifications];

- (id<SINNotificationResult>)relayRemotePushNotification:(NSDictionary *)userInfo

Parameters

userInfo

Remote notification payload which was transferred with an Apple Push Notification. and received via [UIApplicationDelegate application:didReceiveRemoteNotification:].

Return Value

Value indicating initial inspection of push notification.

Declared In

SINClient.h

– registerPushNotificationData: required method

Register device-specific data that can be used to identify this device and tie it to an Apple Push Notification device token.

- (void)registerPushNotificationData:(NSData *)pushNotificationData

Parameters

pushNotificationData

Device-specific data that can be used to tie a device to a specific Apple Push Notification device token

The pushNotificationData is what will be passed back in [SINCallDelegate call:shouldSendPushNotifications:] in the caller’s application, unless the application on the destination device (the device on which this method is called) is not running in the background, and is required to woken up it via a Apple Push Notification.

See [UIApplication registerForRemoteNotificationTypes:] on how to obtain the current device token.

See Also

Declared In

SINClient.h

– unregisterPushNotificationData required method

Unregister previously registered device-specific data that is used to identify this device and tie it to an Apple Push Notification device token.

- (void)unregisterPushNotificationData

Discussion

If it is unwanted that the user receives further remote push notifications for Sinch calls, this method should be used to unregister the push data.

Declared In

SINClient.h

– registerPushNotificationDeviceToken:type:apsEnvironment: required method

Register push notification device token for using “Sinch Managed Push Notifications”. The preferred way of enabling push notifications is to use SINManagedPush which will automatically register the device token with the client, but this method can also be used directly.

- (void)registerPushNotificationDeviceToken:(NSData *)deviceToken type:(NSString *)pushType apsEnvironment:(SINAPSEnvironment)apsEnvironment

Parameters

deviceToken

A token that identifies the device to APNs.

pushType

SINPushType NSString constant, i.e. SINPushTypeVoIP or SINPushTypeRemote

apsEnvironment

Specification of which Apple Push Notification Service environment the device token is bound to.

Declared In

SINClient.h

– unregisterPushNotificationDeviceToken required method

Unregister push notification device token when using “Sinch Managed Push Notifications” Example if the user log out, the device token should be unregistered.

- (void)unregisterPushNotificationDeviceToken

Declared In

SINClient.h

– setPushNotificationDisplayName: required method

Specify a display name to be used when the Sinch client sends a push notification on behalf of the local user (e.g. for an outgoing call). This will only be used when using [SINClient enableManagedPushNotifications].

- (void)setPushNotificationDisplayName:(NSString *)displayName

Parameters

displayName

display name may at most be 255 bytes (UTF-8 encoded) long.

Discussion

Display name is included in a push notification on a best-effort basis. For example, if the target device has very limited push payload size constraints (e.g iOS 7 can only handle 255 byte push notification payload), then the display name may not be included.

Declared In

SINClient.h

– callClient required method

Returns the call client object for placing and receiving calls.

- (id<SINCallClient>)callClient

Declared In

SINClient.h

– audioController required method

Retrieve the interface for the audio controller, which provides access to various audio related functionality, such as muting the microphone, enabling the speaker, and playing ring tones.

- (id<SINAudioController>)audioController

Declared In

SINClient.h

– videoController required method

Retrieve the interface for the video controller, which provides access to video related functionality.

- (id<SINVideoController>)videoController

Declared In

SINClient.h