Login Kit

Login Kit iOS gives you access to two Snapchat features, login and identity. Logging in via Snapchat removes the obstacles of signup and login for new users. The display name and Bitmoji avatar give users a familiar identity within your app.

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:

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

// swift

import SCSDKLoginKit

let loginButton = SCSDKLoginButton() { (success : Bool, error : Error?) in
    // do something
}

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

// swift

import SCSDKLoginKit

SCSDKLoginClient.login(from: viewController) { (success : Bool, error : Error?) in
    // do something
}

// 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:

// swift

import SCSDKLoginKit

func application(
  _ app: UIApplication,
  open url: URL,
  options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
  ...
    if SCSDKLoginClient.application(app, open: url, options: options) {
      return true
    }
  ...
}

// 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:

// 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
})

// 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 external ID

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:

// 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
})

// 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. To enable unlinking, add an unlink authorization option and revoke the previous access token.

// swift

import SCSDKLoginKit

SCSDKLoginClient.unlinkCurrentSessionWithCompletion { (success: Bool) in
  // do something
}

// objective-c

#import <SCSDKLoginKit/SCSDKLoginKit.h>

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

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.

// swift

import SCSDKLoginKit

SCSDKLoginClient.unlinkAllSessionsWithCompletion { (success: Bool) in
  // do something
}

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

What’s next

• Dig deeper. See our API reference docs for iOS.
• Something not working? Report bugs and doc issues here so we can make it better for you.