SINClient

Objective-C

@protocol SINClient <NSObject>

Swift

protocol SINClient : NSObjectProtocol

The SINClient is the Sinch SDK entry point.

Important

Thread safety notes: All interaction should be done on main thread/main GCD queue.

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.

Important

user IDs are restricted to the character set “ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghjiklmnopqrstuvwxyz0123456789-_=”, and must be no longer than 255 bytes.

  • Example:

    // Instantiate a client object using the client factory.
NSError *error;
id<SINClient> client = [Sinch clientWithApplicationKey:@"<APPLICATION KEY>"
                                       environmentHost:@"ocra.api.sinch.com"
                                                userId:@"<USERID>"
                                               error:&error];

// Enable push notifications
[client enableManagedPushNotifications];

// Assign delegate. It is required to implement
// -[SINClientDelegate client:requiresRegistrationCredentials:]
// and provide a authorization token (JWT) to allow the User to register
// and the client to successfully start.
client.delegate = ... ;

// Start the client
[client start];

// Use SINCallClient to place and receive calls
[client.callClient callUserWithId:...]

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

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

    See

    SINClientDelegate

    Declaration

    Objective-C

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

    Swift

    weak var delegate: SINClientDelegate! { get set }

  • ID of the local user

    Declaration

    Objective-C

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

    Swift

    var userId: String! { get }

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

    Method should be called before calling -[SINClient start].

    See

    -[SINClient enableManagedPushNotifications]

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (void)setSupportPushNotifications:(BOOL)supported;

    Swift

    func setSupportPushNotifications(_ supported: Bool)

    Parameters

    supported

    Enable or disable support for push notifications.

  • 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).

    (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].

    See

    -[SINClient registerPushNotificationDeviceToken:type:apsEnvironment:]

    See

    -[SINClient unregisterPushNotificationDeviceToken]

    See

    -[SINClient relayPushNotificationPayload:]

    Throws

    Throws:

    • NSInternalInconsistencyException if the method is invoked after Sinch client has already been started

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (void)enableManagedPushNotifications;

    Swift

    func enableManagedPushNotifications()

  • Start client to enable the calling functionality.

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

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (void)start;

    Swift

    func start()

  • Terminate client when the Sinch functionality is no longer needed. Note that this will terminate the client gracefully in the sense that the client will even after this method is invoked be allowed some time to complete currently pending tasks, for example completing pending HTTP requests.

    It is strongly recommended to initiate the Sinch client, start it, but not terminate it, during the lifetime of the running application. The reason is that initializing and (re-)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 -[SINClient terminateGracefully] to relinquish certain resources. This method should always be called before the application code releases its last reference to the client.

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (void)terminateGracefully;

    Swift

    func terminateGracefully()

  • Check whether client is successfully started.

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (BOOL)isStarted;

    Swift

    func isStarted() -> Bool

    Return Value

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

  • Method used to forward a push notification dictionary when using “Sinch Managed Push Notifications” (-[SINClient enableManagedPushNotifications])

    See

    SINNotificationResult

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (id<SINNotificationResult>)relayPushNotification:(NSDictionary *)userInfo;

    Parameters

    userInfo

    VoIP push notification payload which was transferred with an Apple Push Notification.

    Return Value

    Value indicating initial inspection of push notification.

  • 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.

    Throws

    Throws:

    • NSInternalInconsistencyException if support for push notification has not been previously enabled with -[SINClient setSupportPushNotifications:]
    • NSInvalidArgumentException if deviceToken or pushType are nil

    See

    SINAPSEnvironment

    See

    SINPushTypeVoIP

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

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

    Swift

    func registerPushNotificationDeviceToken(_ deviceToken: Data!, type pushType: String!, apsEnvironment: SINAPSEnvironment)

    Parameters

    deviceToken

    A token that identifies the device to APNs.
    pushType

    SINPushType NSString constant, i.e. SINPushTypeVoIP
    apsEnvironment

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

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

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (void)unregisterPushNotificationDeviceToken;

    Swift

    func unregisterPushNotificationDeviceToken()

  • 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].

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (BOOL)setPushNotificationDisplayName:(NSString *)displayName
                                 error:(NSError **)error;

    Swift

    func setPushNotificationDisplayName(_ displayName: String!) throws

    Parameters

    displayName

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

    Error object that describes the problem in case the method returns NO. It can be nil.

    Return Value

    A boolean value indicating whether the display name was set successfully. If return value is NO, the value of error will contain more specific info about the failure.

  • Returns the call client object for placing and receiving calls.

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (id<SINCallClient>)callClient;

  • 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.

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (id<SINAudioController>)audioController;

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

    Important

    Thread safety notes: Should be called on main thread/main GCD queue.

    Declaration

    Objective-C

    - (id<SINVideoController>)videoController;