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 namehttps://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 containsnapchat
,bitmoji-sdk
, anditms-apps
.CFBundleURLSchemes
(string-array): This should contain your redirect URL’s scheme. If your redirect URL ismyapp://snap-kit/oauth2
, this field would bemyapp
.
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.