From 413cc289af1af88d9e0e8968d76897484f9872cd Mon Sep 17 00:00:00 2001 From: Hassan Shahbazi Date: Thu, 5 Mar 2020 18:12:07 +0200 Subject: [PATCH 1/2] Update Readme (#96) --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 52 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 5279b6c..f1b5b60 100644 --- a/README.md +++ b/README.md @@ -16,19 +16,12 @@ Example Podfile: ``` platform :ios, '9.0' -source 'https://github.com/CocoaPods/Specs.git' +source 'https://cdn.cocoapods.org/' source 'https://github.com/somia/ninchat-podspecs.git' -def all_pods - pod 'NinchatSDK', '~> 0.0.1' -end - -target 'NinchatSDKTestClient' do - all_pods -end - -target 'NinchatSDKTestClientTests' do - all_pods +target 'HOST_APPLICATION_TARGET' do + use_frameworks! + pod 'NinchatSDK', '~> 0.0.42' end ``` @@ -36,6 +29,26 @@ Install by running `pod install`. NOTE that `use_frameworks!` is optional. +## Breaking Changes + +Starting **version 0.0.42**, the SDK supports session resumption. Consider the following breaking changes if you are updating the SDK to versions >= 0.0.42 from earlier versions. + +### Session initialization + +Since session resumption feature requires credentials, `start(callBack:)` includes a `NINSessionCredentials?` parameter which is used for resuming the session later. + +```swift +ninchatSession.start { (credentials: NINSessionCredentials?, error: Error?) in  } +``` + +### Delegate methods + +There might be cases where provided credentials are not valid for resuming a session. In such cases, the following delegate would be used to initiate a new session. + +```swift +func ninchatDidFail(toResumeSession session: NINChatSession) -> Bool {} +``` + ## Usage #### Creating the API client @@ -68,19 +81,35 @@ ninchatSession.appDetails = "app-name/version (more; details)" #### Starting the API client -The SDK must perform some asynchornous networking tasks before it is ready to use; this is done by calling the `start` method as follows: +The SDK must perform some asynchornous networking tasks before it is ready to use; this is done by calling the `start` method as follows. The callback includes credentials that could be saved for resuming the session later. ```swift -ninchatSession.start { [weak self] error in +ninchatSession.start { (credentials: NINSessionCredentials?, error: Error?) in if let error = error { - log.error("Ninchat SDK chat session failed to start with error: \(error))") - self?.ninchatSession = nil - //TODO insert your error handling steps here - return + /// Some errors in starting a new session. } + /// Save/Cache `credentials` for resuming the session later. } ``` +#### Resuming a session + +Starting **version 0.0.42**, the SDK provides support to resume a session. In case of any issues in resuming the session using provided credentials, the corresponded delegate is called to ask if a new session should be started or not. + +```swift +ninchatSession.start(with: credentials) { (credentials: NINSessionCredentials?, error: Error?) in + if let error = error { + /// Some errors in resuming the session. + } + /// Update saved/cached `credentials` with the new one. +} + +/// Called when credentials are not valid. +func ninchatDidFail(toResumeSession session: NINChatSession) -> Bool { + /// Return `true` if the SDK should start a new session. + return true +} +``` #### Showing the SDK UI @@ -145,6 +174,12 @@ func ninchat(_ session: NINChatSession, onLowLevelEvent params: NINLowLevelClien func ninchat(_ session: NINChatSession, didOutputSDKLog message: String) { log.debug("** NINCHAT SDK **: \(message)") } + +/// This method is called when the SDK was unable to resume a session using provided credentials. +/// The return value determines if the SDK should initiate a new session or not. +func ninchatDidFail(toResumeSession session: NINChatSession) -> Bool { + return true +} ``` #### Info.plist keys Required by the SDK From 88f49392b4e81f322eadc075d79e8b0f6ba7dbec Mon Sep 17 00:00:00 2001 From: Hassan Shahbazi Date: Tue, 10 Mar 2020 20:14:04 +0200 Subject: [PATCH 2/2] add backward compatibility API (#98) --- NinchatSDK/NINChatSession.h | 10 ++++++++-- NinchatSDK/NINChatSession.m | 10 ++++++++-- README.md | 35 ++++++++++++++--------------------- 3 files changed, 30 insertions(+), 25 deletions(-) diff --git a/NinchatSDK/NINChatSession.h b/NinchatSDK/NINChatSession.h index 01b69c1..cc55777 100644 --- a/NinchatSDK/NINChatSession.h +++ b/NinchatSDK/NINChatSession.h @@ -27,6 +27,7 @@ * * The return value indicates if the SDK should initiate a new chat session or not. */ +@optional -(BOOL) ninchatDidFailToResumeSession:(NINChatSession*_Nonnull)session; /** @@ -134,7 +135,7 @@ /** * Starts the API engine using given credentials. Must be called before other API methods. * If callback returns the error indicating invalidated credentials, the caller is responsible to decide - * for using `-startWithCallback:` and startign a new chat session. + * for using `-startWithCallback:` and starting a new chat session. */ -(void)startWithCredentials:(nonnull NINSessionCredentials*)credentials andCallback:(nonnull startCallbackBlock)callbackBlock; @@ -142,7 +143,12 @@ * Starts the API engine. Must be called before other API methods. The method creates * a new user and a new session. The caller must wait for the callback block to be called without errors. */ --(void) startWithCallback:(nonnull startCallbackBlock)callbackBlock; +-(void) startWithCredentialCallback:(nonnull startCallbackBlock)callbackBlock; + +/** + * Add backward compatibility for applications to omit credentials and session resumption features. + * */ +-(void) startWithCallback:(nonnull void(^)(NSError* _Nullable))callbackBlock; /** * Returns the view controller for the Ninchat UI. diff --git a/NinchatSDK/NINChatSession.m b/NinchatSDK/NINChatSession.m index 734f2b0..6cd00c7 100644 --- a/NinchatSDK/NINChatSession.m +++ b/NinchatSDK/NINChatSession.m @@ -216,7 +216,7 @@ -(void) startWithCredentials:(nonnull NINSessionCredentials*)credentials andCall * 1. Using that configuration, starts a new chat session * 2. Retrieves the queues available for this realm (realm id from site configuration) */ --(void) startWithCallback:(nonnull startCallbackBlock)callbackBlock { +-(void) startWithCredentialCallback:(nonnull startCallbackBlock)callbackBlock { __weak typeof(self) weakSelf = self; [self sdklog:@"Starting a new chat session"]; @@ -237,6 +237,12 @@ -(void) startWithCallback:(nonnull startCallbackBlock)callbackBlock { self.resumeSession = NO; } +-(void)startWithCallback:(nonnull void (^)(NSError *_Nullable))callbackBlock { + [self startWithCredentialCallback:^(NINSessionCredentials *credentials, NSError *error) { + callbackBlock(error); + }]; +} + /** Fetching site configurations usable by both approaches to opening sessions */ -(void) fetchSiteConfigurations:(nonnull void (^)(NSError* _Nullable))callbackBlock { __weak typeof(self) weakSelf = self; @@ -297,7 +303,7 @@ -(void) continueSessionWithCredentials:(nonnull NINSessionCredentials*)credentia // [weakSelf.sessionManager closeOldSession:credentials.sessionID]; if ((error != nil && [error.userInfo[@"message"] isEqualToString:@"user_not_found"]) || !canContinueSession) { if ([weakSelf.delegate respondsToSelector:@selector(ninchatDidFailToResumeSession:)] && [weakSelf.delegate ninchatDidFailToResumeSession:weakSelf]) {} - [weakSelf startWithCallback:callbackBlock]; + [weakSelf startWithCredentialCallback:callbackBlock]; return; } diff --git a/README.md b/README.md index f1b5b60..dd1b1b7 100644 --- a/README.md +++ b/README.md @@ -29,26 +29,6 @@ Install by running `pod install`. NOTE that `use_frameworks!` is optional. -## Breaking Changes - -Starting **version 0.0.42**, the SDK supports session resumption. Consider the following breaking changes if you are updating the SDK to versions >= 0.0.42 from earlier versions. - -### Session initialization - -Since session resumption feature requires credentials, `start(callBack:)` includes a `NINSessionCredentials?` parameter which is used for resuming the session later. - -```swift -ninchatSession.start { (credentials: NINSessionCredentials?, error: Error?) in  } -``` - -### Delegate methods - -There might be cases where provided credentials are not valid for resuming a session. In such cases, the following delegate would be used to initiate a new session. - -```swift -func ninchatDidFail(toResumeSession session: NINChatSession) -> Bool {} -``` - ## Usage #### Creating the API client @@ -92,9 +72,20 @@ ninchatSession.start { (credentials: NINSessionCredentials?, error: Error?) in } ``` +**Note: You still can initiate the session using the legacy interface without any credentials involved:** + +```swift +ninchatSession.start { (error: Error?) in + if let error = error { + /// Some errors in starting a new session. + } + /// Show the SDK UI. +} +``` + #### Resuming a session -Starting **version 0.0.42**, the SDK provides support to resume a session. In case of any issues in resuming the session using provided credentials, the corresponded delegate is called to ask if a new session should be started or not. +Starting **version 0.0.42**, the SDK provides support to resume a session. In case of any issues in resuming the session using provided credentials, the corresponded optional delegate is called to ask if a new session should be started or not. ```swift ninchatSession.start(with: credentials) { (credentials: NINSessionCredentials?, error: Error?) in @@ -104,6 +95,7 @@ ninchatSession.start(with: credentials) { (credentials: NINSessionCredentials?, /// Update saved/cached `credentials` with the new one. } +/// Optional /// Called when credentials are not valid. func ninchatDidFail(toResumeSession session: NINChatSession) -> Bool { /// Return `true` if the SDK should start a new session. @@ -175,6 +167,7 @@ func ninchat(_ session: NINChatSession, didOutputSDKLog message: String) { log.debug("** NINCHAT SDK **: \(message)") } +/// Optional /// This method is called when the SDK was unable to resume a session using provided credentials. /// The return value determines if the SDK should initiate a new session or not. func ninchatDidFail(toResumeSession session: NINChatSession) -> Bool {