Docs

Login Kit iOS

Requirements

  • Client ID from the developer portal
  • iOS version 10.0+

Understanding Scopes

Scopes let your application declare which Login Kit features it wants access to. If a scope is toggleable, the user can deny access to one scope while agreeing to grant access to others.

Login Kit offers the following scopes:

  • https://auth.snapchat.com/oauth2/api/user.display_name: Grants access to the user's Snapchat display name
  • https://auth.snapchat.com/oauth2/api/user.bitmoji.avatar: Grants access to the user's Bitmoji avatar; toggleable by user

When you specify which scopes you'd like, use the full URL, like this:

1
2
3
4
5
  <key>SCSDKScopes</key>
  <array>
    <string>https://auth.snapchat.com/oauth2/api/user.bitmoji.avatar</string>
    <!-- other scopes you might have... -->
  </array>

Getting Started

Get comfortable with the Snap Kit developer portal. This is where you'll actually create and submit your Snap Kit application. Our docs expect you to make changes in the dev portal as well as in your project files.

In your app project in Xcode, add SCSDKCoreKit.framework and SCSDKLoginKit.framework into General > Embedded Binaries.

Add the following fields in your application’s Info.plist file:

  • SCSDKClientId (string): This is your application’s client ID, used for OAuth. Copy it from the developer portal, under App Info > OAuth2 Client ID.
  • SCSDKRedirectUrl (string): This URL will handle and complete login requests. Use any naming convention that works for you, with the URL syntax foo://bar. If you need ideas, you could try myapp://snap-kit/oauth2.
  • SCSDKScopes (string-array): Your application will request scopes of access from the user. For help defining scopes, see the Understanding Scopes section above.
  • LSApplicationQueriesSchemes (string-array): This should contain snapchat, bitmoji-sdk, and itms-apps.
  • CFBundleURLSchemes (string-array): This should contain your redirect URL’s scheme. If your redirect URL is myapp://snap-kit/oauth2, this field would be myapp.

Note: In the Snap Kit developer portal, add the same URL you put in Info.plist to your app's Redirect URLs. Without this, you'll get an error when your app tries to open Snapchat for OAuth.


Initiating Login with Snapchat

First, import the login button. When a user taps the Log In with Snapchat button in your app, it directs them to Snapchat if they have it installed. If not, it prompts them to log in with Snapchat through an in-app web view. Pass in a completion handler to let your app know what to do once users successfully log into Snapchat.

1
2
3
4
5
6
7
// swift

import SCSDKLoginKit

let loginButton = SCSDKLoginButton() { (success : Bool, error : Error?) in
    // do something
}
1
2
3
4
5
6
7
// objective-c

#import <SCSDKLoginKit/SCSDKLoginKit.h>

SCSDKLoginButton *loginButton =  [[SCSDKLoginButton alloc] initWithCompletion:^(BOOL success, NSError * _Nullable error) {
                                  // do something
                               }];

Using a custom UI for login? The SCSDKLoginClient supports that. Pass in a completion handler to let your app know what to do once users successfully log into Snapchat.

1
2
3
4
5
6
7
// swift

import SCSDKLoginKit

SCSDKLoginClient.login(from: viewController) { (success : Bool, error : Error?) in
    // do something
}
1
2
3
4
5
6
7
8
// objective-c

#import <SCSDKLoginKit/SCSDKLoginKit.h>

[SCSDKLoginClient loginFromViewController:viewController
                               completion:^(BOOL success, NSError * _Nullable error) {
                                  // do something
                               }];

Finishing Login with Snapchat

Once your user successfully authorizes your app to log in with Snapchat, you need to handle the deeplink that comes from Snapchat to get the access token.

In AppDelegate.m, use the SCSDKLoginClient interface to receive the deeplink:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// swift

import SCSDKLoginKit

func application(
  _ app: UIApplication,
  open url: URL,
  options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
  ...
    if SCSDKLoginClient.application(app, open: url, options: options) {
      return true
    }
  ...
}
1
2
3
4
5
6
7
8
9
10
11
12
13
// objective-c

#import <SCSDKLoginKit/SCSDKLoginKit.h>

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
...
              if ([SCSDKLoginClient application:application openUrl:url options:options]) {
                return YES;
              }
...
}

Note: Access to user data expires after 90 days of inactivity on your app.


Sending Requests to Get User Data

Currently, we support two requests for user data:

  • Get display name
  • Get Bitmoji avatar

Use the SCSDKLoginClient to fetch the Bitmoji avatar URL and Snapchat display name:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// swift

let graphQLQuery = "{me{displayName, bitmoji{avatar}}}"

let variables = ["page": "bitmoji"]

SCSDKLoginClient.fetchUserData(withQuery: graphQLQuery, variables: variables, success: { (resources: [AnyHashable: Any]?) in
  guard let resources = resources,
    let data = resources["data"] as? [String: Any],
    let me = data["me"] as? [String: Any] else { return }

  let displayName = me["displayName"] as? String
  var bitmojiAvatarUrl: String?
  if let bitmoji = me["bitmoji"] as? [String: Any] {
    bitmojiAvatarUrl = bitmoji["avatar"] as? String
  }
}, failure: { (error: Error?, isUserLoggedOut: Bool) in
	// handle error
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// objective-c

NSString *graphQLQuery = @"{me{displayName, bitmoji{avatar}}}";

NSDictionary *variables = @{@"page": @"bitmoji"};

[SCSDKLoginClient fetchUserDataWithQuery:graphQLQuery
                               variables:variables
                                 success:^(NSDictionary *resources) {
                                   NSDictionary *data = resources[@"data"];
                                   NSDictionary *me = data[@"me"];
                                   NSString *displayName = me[@"displayName"];
                                   NSDictionary *bitmoji = me[@"bitmoji"];
                                   NSString *bitmojiAvatarUrl = bitmoji[@"avatar"];
                               } failure:^(NSError * error, BOOL isUserLoggedOut) {
                                   // handle error as appropriate
                               }];

Sending Requests to Get the externalId

Once a user logs into your app with Snapchat, you can make requests for their external ID. This is a unique identifier for this user on your app. The following example requests this identifier for the user that is currently logged in:

1
2
3
4
5
6
7
8
9
10
11
12
13
// swift

let graphQLQuery = "{me{externalId}}"

SCSDKLoginClient.fetchUserData(withQuery: graphQLQuery, variables: nil, success: { (resources: [AnyHashable: Any]?) in
  guard let resources = resources,
    let data = resources["data"] as? [String: Any],
    let me = data["me"] as? [String: Any] else { return }

  let externalId = me["externalId"] as? String
}, failure: { (error: Error?, isUserLoggedOut: Bool) in
	// handle error
})
1
2
3
4
5
6
7
8
9
10
11
12
13
// objective-c

NSString *graphQLQuery = @"{me{externalId}}";

[SCSDKLoginClient fetchUserDataWithQuery:graphQLQuery
                               variables:nil
                  success:^(NSDictionary *resources) {
                    NSDictionary *data = resources[@"data"];
                    NSDictionary *me = data[@"me"];
                    NSString *externalId = me[@"externalId"];
} failure:^(NSError * error, BOOL isUserLoggedOut) {
  // handle error as appropriate
}];

Unlinking

Unlinking Current Session

A user might want to unlink their current OAuth2 session, which means they’ll lose access to their Bitmoji avatar and display name in your app in this specific session. The clearToken() method below can be used to clear the access and refresh tokens locally. Note: the unlinkCurrentSessionWithCompletion method has been deprecated.

1
2
3
// swift

class func clearToken()
1
2
3
// objective-c

+ (void)clearToken;

Once you add and execute this line, your requests from this session to Snapchat will get permission errors. For a good user experience, make sure you stop making those requests after the user unlinks their account with this session.


Unlinking All Sessions

A user might want to unlink all existing OAuth2 sessions, which means they’ll lose access to their Bitmoji avatar and display name in your app for all sessions. The app will also be removed from the Connected Apps page in Snapchat. To enable unlinking, add an unlink authorization option and revoke the previous access token.

1
2
3
4
5
6
7
// swift

import SCSDKLoginKit

SCSDKLoginClient.unlinkAllSessionsWithCompletion { (success: Bool) in
  // do something
}
1
2
3
4
5
6
7
// objective-c

#import <SCSDKLoginKit/SCSDKLoginKit.h>

[SCSDKLoginClient unlinkAllSessionsWithCompletion:^(BOOL success) {
  // do something
}];

Once you add and execute this line, your requests to Snapchat will get permission errors. For a good user experience, make sure you stop making those requests after the user unlinks their account with all sessions.


Verify With Snapchat

Verify with Snapchat is a feature of the Login Kit SDK that allows users to quickly register in third-party applications using the phone number attached to their Snapchat account.

Verify and Connect

Developers can use Verify and Connect to check an inputted phone number and verify that it matched the one on file for a user's Snapchat account. Users will be redirected to Snapchat to verify their phone number; once the number has been confirmed, they will be redirected to the Login / OAuth modal. After authorization, users will return to the 3PA connected and verified.

1
2
3
// swift

class func verifyAndLogin(from: UIViewController, phone: String?, region: String?, completion: SCSDKVerifyAndLoginCompletionBlock) -> Void
1
2
3
4
5
6
// objective-c

+ (void)verifyAndLoginFromViewController:(UIViewController *)viewController
                                   phone:(NSString *)phone
                                  region:(NSString *)region
                              completion:(SCSDKVerifyAndLoginCompletionBlock) completion

Verify Only

Verify Only allows developers to verify phone numbers on demand. Developers are able to run the verification flow outside of the authorization flow, allowing Verify With Snapchat to be triggered at different points of the application. In this flow, Snapchat will only Verify the inputted phone number and will not redirect users to the Login / Auth modal for authorization.

1
2
// swift
class func verify(from: UIViewController, phone: String?, region: String?, completion: SCSDKVerifyCompletionBlock) -> Void
1
2
3
4
5
// objective-c
+ (void)verifyFromViewController:(UIViewController *)viewController
                           phone:(NSString *)phone
                          region:(NSString *)region
                      completion:(SCSDKVerifyCompletionBlock) completion

Note: Snapchat will use a phone number only to verify if it is used by a Snapchat account. Snapchat will not use any of the phone number data for advertising purposes. If a phone number is not registered on Snapchat, we will ask users to update their Snapchat account with the new number.


As part of the verification flow, we store the result of the phone number verification in our server. This allows you to confirm if the phone number you requested was successfully verified by Snapchat.


Endpoint - https://api.snapkit.com/v1/phoneverify/verify_result

Description - this endpoint takes the following HTTPS POST parameters and returns the result of the verification. It will return true if the phone number was successfully verified and false otherwise.

Parameters:

  • phone_number_id - the phone id returned from the Snapchat SDK completion handler.
  • phone_number_verify_id - the verify id returned from the Snapchat SDK completion handler.
  • phone_number - the phone number your application attempted to verify.
  • region - the two digit country code region of the phone number your application attempted to verify.

What’s Next