Inherits from NSObject
Declared in KiiSocialConnect.h

Overview

An interface to link users to social networks

The SDK currently support the following social networks :

  1. Facebook
  2. Twitter
  3. Sina Weibo
  4. Googleplus
  5. QQ

The following services will not be supported after July 31st, 2019:

  1. LinkedIn
  2. Yahoo
  3. Dropbox
  4. Box
  5. Renren
  6. Microsoft Live
  7. OpenID Connect Simple

Class Methods

accessTokenDictionary:

Retrieve the current user’s social network access token object as NSDictionary. If the user is not associated with the specified provider, returns nil. The dictionary would be cached after the login and link has been executed. Cache would be cleared when new login, link or unlink has been executed. (Regardless of same/different KiiConnectorProvider is specified)

+ (nullable NSDictionary *)accessTokenDictionary:(KiiConnectorProvider)provider

Parameters

provider

One of the supported KiiConnectorProvider values.

Return Value

An NSDictionary representing the access token’s object.

Discussion

Retrieve the current user’s social network access token object as NSDictionary. If the user is not associated with the specified provider, returns nil. The dictionary would be cached after the login and link has been executed. Cache would be cleared when new login, link or unlink has been executed. (Regardless of same/different KiiConnectorProvider is specified)

Please keep the returned value in your application program before execute new login/ link session when you sequencially link the several social network providers with the same user if you need to use them. Following parameters can be assigned to NSDictionary’s key.

Key Value type Value Note
oauth_token String Required for accessing social network API.
oauth_token_secret String Required to generate signature when you call social network API. Present in the bundle for Twitter.
provider_user_id String User id provided by social network. ex.) 'xoauth_yahoo_guid' used by Yahoo profile API.
kii_new_user NSNumber(BOOL) Indicates if user was created during connection.
openID NSString OpenId identifier Present in QQ
oauth_token_expires NSDate Oauth expirations date Present only if logged in using UI and selected providers (Facebook, Google, Box, Renren, Sina Weibo, and Microsoft Live)
id_token NSString ID token provided by OpenID Provider. This field is provided when is used. Present in OpenID Connect
refresh_token NSString Refresh token provided by OpenID Provider. This field is provided when is used and configured OpenID Provider supports refresh token. Present in OpenID Connect

Exceptions

NSInvalidArgumentException

will be thrown if KiiSocialNetworkName is passed as provider.

Declared In

KiiSocialConnect.h

getAccessTokenDictionaryForNetwork:

Retrieve the current user’s access token object by NSDictionary from a social network (Deprecated: This method is deprecated. Use [KiiSocialConnect accessTokenDictionary:] instead.)

+ (nullable NSDictionary *)getAccessTokenDictionaryForNetwork:(KiiSocialNetworkName)network

Parameters

network

One of the supported KiiSocialNetworkName values.

Return Value

An NSDictionary representing the access token’s object.

Discussion

Retrieve the current user’s access token object by NSDictionary from a social network

The network must be set up and linked to the current user. It is recommended you save this to preferences for multi-session use. Following parameters can be assigned to NSDictionary’s key.

Facebook

Key Value type Value Note
access_token String Required for accessing social network API.
access_token_expires String Expiration date for this token

Twitter

Key Value type Value Note
oauth_token String Required for accessing social network API.
oauth_token_secret String Required to generate signature when you call social network API.

QQ

Key Value type Value Note
access_token String Required for accessing social network API.
openID String Required for accessing social network API.

Kii Social Network Connect

Key Value type Value Note
oauth_token String Required for accessing social network API.
oauth_token_secret String Required to generate signature when you call social network API. Present in the bundle for Twitter, LinkedIn, and Yahoo.
provider_user_id String User id provided by social network. ex.) 'xoauth_yahoo_guid' used by Yahoo profile API.
kii_new_user NSNumber(BOOL) Indicates if user was created during connection.
id_token NSString ID token provided by OpenID Provider. This field is provided when is used. Present in OpenID Connect
refresh_token NSString Refresh token provided by OpenID Provider. This field is provided when is used and configured OpenID Provider supports refresh token. Present in OpenID Connect

Declared In

KiiSocialConnect.h

getAccessTokenExpiresForNetwork:

Retrieve the current user’s access token expiration date from a social network (Deprecated: This method is deprecated. Use [KiiSocialConnect accessTokenDictionary:] instead.)

+ (nullable NSDate *)getAccessTokenExpiresForNetwork:(KiiSocialNetworkName)network

Parameters

network

One of the supported KiiSocialNetworkName values.

Return Value

An NSDate representing the access token’s expiration date, nil if none available.

Discussion

Retrieve the current user’s access token expiration date from a social network

The network must be set up and linked to the current user. It is recommended you save this to preferences for multi-session use.

Declared In

KiiSocialConnect.h

getAccessTokenForNetwork:

Retrieve the current user’s access token from a social network (Deprecated: This method is deprecated. Use [KiiSocialConnect accessTokenDictionary:] instead.)

+ (nullable NSString *)getAccessTokenForNetwork:(KiiSocialNetworkName)network

Parameters

network

One of the supported KiiSocialNetworkName values.

Return Value

An NSString representing the access token, nil if none available.

Discussion

Retrieve the current user’s access token from a social network

The network must be set up and linked to the current user. It is recommended you save this to preferences for multi-session use.

Declared In

KiiSocialConnect.h

handleOpenURL:

Required method by KiiSocialNetwork (Deprecated: Not usable on new social connect login mechanism from v2.2.1.)

+ (BOOL)handleOpenURL:(NSURL *)url

Parameters

url

The URL that is returned by Facebook authentication through delegate.

Discussion

Required method by KiiSocialNetwork

This method must be placed in your AppDelegate file in order for the SNS to properly authenticate with KiiSocialConnect:

// Pre iOS 4.2 support
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url {
    return [KiiSocialConnect handleOpenURL:url];
}

// For iOS 4.2+ support
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
                                       sourceApplication:(NSString *)sourceApplication
                                              annotation:(id)annotation {
    return [KiiSocialConnect handleOpenURL:url];
}

Declared In

KiiSocialConnect.h

linkCurrentUser:options:block:

Link the currently logged in user with supported social networks (Facebook, Twitter, Renren, Google and QQ).

+ (void)linkCurrentUser:(KiiConnectorProvider)provider options:(NSDictionary *)options block:(KiiSCNBlock)block

Parameters

provider

One of the supported KiiConnectorProvider values.

options

A dictionary of key/values to pass to KiiSocialConnect. This is mandatory, can not be nil.

block

To be called upon link completion. This is mandatory.

Discussion

Link the currently logged in user with supported social networks (Facebook, Twitter, Renren, Google and QQ).

The provider should be valid KiiConnectorProvider values. Otherwise, an exception will be raised.
Snippet for link with social network:

[KiiSocialConnect linkCurrentUser:kiiConnectorFacebook
                          options:@{@"accessToken":@"access_token"}
                            block:^(KiiUser *user, KiiConnectorProvider provider, NSError *error) {
    if (error == nil) {
        // link successful. Do someting with the user.
    } else {
        // something went wrong.
    }
}];

Following parameters can be assigned to NSDictionary’s key.

Facebook, Renren, GooglePlus

Key Value type Value Note
accessToken String Required for accessing social network API.

Twitter

Key Value type Value Note
accessToken String Required for accessing social network API.
accessTokenSecret String Required to generate signature when you call social network API.

QQ

Key Value type Value Note
accessToken String Required for accessing social network API.
openID String Required for accessing social network API.

Warning: Dropbox, Box, Yahoo, LinkedIn, Microsoft Live, Sina Weibo is not supported, passing it will throw an exception.

Exceptions

NSInvalidArgumentException

will be thrown if options is not valid.

NSInvalidArgumentException

will be thrown if block is nil.

NSInvalidArgumentException

will be thrown if unsupported provider or KiiSocialNetworkName is passed as provider.

Declared In

KiiSocialConnect.h

logIn:options:block:

Login with specified social network.

+ (void)logIn:(KiiConnectorProvider)provider options:(nullable NSDictionary *)options block:(KiiSCNBlock)block

Parameters

provider

One of the supported KiiConnectorProvider values.

options

A dictionary of key/values to pass to KiiSocialConnect. This can be nil if using UI approach.

block

To be called upon login completion.

Discussion

Login with specified social network.

Note: Login with UI provided by SDK will be not supported after July 31st, 2019.

This will initiate the login process for the given network, with or without UI handled by SDK. If you prefer to handle login UI or using provider specific SDK to obtain access token, pass required params (acces token, access token secret, open ID) according to each provider. Other than kiiConnectorQQ, Kii SDK can handle the UI by passing nil into the options. If the social network user has already linked with a KiiUser, that user will be used as signed user. Otherwise, KiiCloud creates a new user and link with the specified social network account. The provider should be valid KiiConnectorProvider values. Otherwise, an exception will be raised.
Snippet for Login with social network without UI:

[KiiSocialConnect logIn:kiiConnectorFacebook
                options:@{@"accessToken":@"access_token"}
                  block:^(KiiUser *user, KiiConnectorProvider provider, NSError *error) {
    if (error == nil) {
        // link successful. Do someting with the user.
    } else {
        // something went wrong.
    }
}];

Snippet for Login with social network with UI:

[KiiSocialConnect logIn:kiiConnectorFacebook
                options:nil
                  block:^(KiiUser *user, KiiConnectorProvider provider, NSError *error) {
    if (error == nil) {
        // link successful. Do someting with the user.
    } else {
        // something went wrong.
    }
}];

Following parameters can be assigned to NSDictionary’s key.

Facebook, Renren, Googleplus

Key Value type Value Note
accessToken String Required for accessing social network API.

Twitter

Key Value type Value Note
accessToken String Required for accessing social network API.
accessTokenSecret String Required to generate signature when you call social network API.

QQ

Key Value type Value Note
accessToken String Required for accessing social network API.
openID String Required for accessing social network API.

Warning: Dropbox, Box, Yahoo, LinkedIn, Microsoft Live, Sina Weibo can only use login with UI.

Exceptions

NSInvalidArgumentException

will be thrown if options is not valid.

NSInvalidArgumentException

will be thrown if block is nil.

NSInvalidArgumentException

will be thrown if KiiSocialNetworkName is passed as provider.

Declared In

KiiSocialConnect.h

logInNavigationController:block:

Get UINavigationController for login with specified social network.

+ (UINavigationController *)logInNavigationController:(KiiConnectorProvider)provider block:(KiiSCNBlock)block

Parameters

provider

One of the supported KiiConnectorProvider values.

block

To be called upon login completion.

Return Value

navigation controller for login, no return nil. Please present this controller yourself.

Discussion

Get UINavigationController for login with specified social network.

Note: Login with UI provided by SDK will be not supported after July 31st, 2019.

This will initiate the login process for the given network, with or without UI handled by SDK. If you prefer to handle login UI or using provider specific SDK to obtain access token, pass required params (acces token, access token secret, open ID) according to each provider. Other than kiiConnectorQQ, Kii SDK can handle the UI by passing nil into the options. If the social network user has already linked with a KiiUser, that user will be used as signed user. Otherwise, KiiCloud creates a new user and link with the specified social network account. The provider should be valid KiiConnectorProvider values. Otherwise, an exception will be raised.
Snippet for Login with social network without UI:

UINavigationController nc = [KiiSocialConnect logInNavigationController:kiiConnectorFacebook block:^(KiiUser user, KiiConnectorProvider provider, NSError *error) { if (error == nil) { // link successful. Do someting with the user. } else { // something went wrong. } }]; [{instance of top view controoler} presentViewController:nc animated:YES completion:nil];

Warning: Dropbox, Box, Yahoo, LinkedIn, Microsoft Live, Sina Weibo can only use login with UI.

Exceptions

NSInvalidArgumentException

will be thrown if block is nil.

NSInvalidArgumentException

will be thrown if KiiSocialNetworkName is passed as provider.

Declared In

KiiSocialConnect.h

setupNetwork:withKey:andSecret:andOptions:

Set up a reference to one of the supported KiiSocialNetworks. (Deprecated: Not usable on new social connect login mechanism from v2.2.1.)

+ (void)setupNetwork:(KiiSocialNetworkName)network withKey:(nullable NSString *)key andSecret:(nullable NSString *)secret andOptions:(nullable NSDictionary *)options

Parameters

network

One of the supported KiiSocialNetworkName values.

key

The SDK key assigned by the social network provider. It should not be nil or empty except for Kii Social Network Connect.In case of QQ just pass nil.

secret

The SDK secret assigned by the social network provider. In case of Twitter, It should not be nil or empty. In case of QQ and Kii Social Network Connect just pass nil.

options

Extra options that can be passed to the SNS, this is not mandatory. Examples could be (Facebook) an NSDictionary of permissions to grant to the authenticated user. In case of qq, twitter and Kii Social Network Connect, options parameter will not be used, please set to nil.

Discussion

Set up a reference to one of the supported KiiSocialNetworks.

The user will not be authenticated or linked to a KiiUser until one of those methods are called explicitly.

Exceptions

NSInvalidArgumentException

will be thrown if key and/or secret is not valid (see description above).

Declared In

KiiSocialConnect.h

unLinkCurrentUser:block:

Unlink the currently logged in user from the social network.

+ (void)unLinkCurrentUser:(KiiConnectorProvider)provider block:(KiiSCNBlock)block

Parameters

provider

One of the supported KiiConnectorProvider values.

block

To be called upon unlink completion. This is mandatory.

Discussion

Unlink the currently logged in user from the social network.

The provider should be valid KiiConnectorProvider values. Otherwise, an exception will be raised.

Snippet for unlink current user with network. :

[KiiSocialConnect unLinkCurrentUser:kiiConnectorFacebook
                              block:^(KiiUser *user, KiiConnectorProvider name, NSError *error) {
    if (error == nil) {
        // unlink successful.
    } else {
        // something went wrong.
    }
}];

Note: This API access to server. Should not be executed in UI/Main thread.

Warning: Dropbox, Box, Yahoo, LinkedIn, Microsoft Live, Sina Weibo is not supported, passing it will throw an exception.

Exceptions

NSInvalidArgumentException

will be thrown if block is nil.

NSInvalidArgumentException

will be thrown if unsupported provider or KiiSocialNetworkName is passed as provider.

Declared In

KiiSocialConnect.h