iOS
Requirements
- Client ID from the developer portal
- iOS version 10.0+
Understand 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>
Get 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 and edit the podfile by adding or modifying the line with 'SnapSDK'.
target '<your-app-name>' do
...
pod 'SnapSDK', '<version>', :subspecs => ['SCSDKLoginKit']
...
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
.
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.
The Snap Kit SDK is initialized on application start-up by default. Auto-initialization can be disabled and the SDK can be manually initialized and de-initialized.
To disable Snap Kit auto-initialization, add the following entry to your app’s Info.plist
file:
<key>SnapKitAutoInit</key>
<false/>
To manually initialize the Snap Kit SDK, call SCSDKSnapKit.initSDK()
.
To de-initialize the Snap Kit SDK, call SCSDKSnapKit.deinitialize()
.
Features
Initiate 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
- Objective C
import SCSDKLoginKit
let loginButton = SCSDKLoginButton() { (success : Bool, error : Error?) in
// Do something
}
#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
- Objective C
import SCSDKLoginKit
SCSDKLoginClient.login(from: viewController) { (success : Bool, error : Error?) in
// Do something
}
#import <SCSDKLoginKit/SCSDKLoginKit.h>
[SCSDKLoginClient loginFromViewController:viewController
completion:^(BOOL success, NSError * _Nullable error) {
// Do something
}];
Finish 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
- Objective C
import SCSDKLoginKit
func application(
_ app: UIApplication,
open url: URL,
options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
...
if SCSDKLoginClient.application(app, open: url, options: options) {
return true
}
...
}
#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;
}
...
}
Access to user data expires after 90 days of inactivity on your app.
Send 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
- Objective C
let builder = SCSDKUserDataQueryBuilder().withDisplayName().withBitmojiTwoDAvatarUrl()
let userDataQuery = builder.build()
// Call fetch API
SCSDKLoginClient.fetchUserData(with:userDataQuery,
success:{ (userData: SCSDKUserData, partialError: Error?) in
let displayName = userData?.displayName;
let bitmojiAvatarURL = userData?.bitmojiTwoDAvatarUrl;
},
failure:{ (error: Error?, isUserLoggedOut: Bool) in
// Handle error
})
SCSDKUserDataQueryBuilder *builder = [[[[SCSDKUserDataQueryBuilder alloc] init] withDisplayName] withBitmojiTwoDAvatarUrl];
SCSDKUserDataQuery *userDataQuery = [builder build];
// Call fetch API
[SCSDKLoginClient fetchUserData:userDataQuery
success:^(SCSDKUserData * _Nullable userData, NSError * _Nullable partialError) {
let displayName = userData.displayName;
let bitmojiAvatarUrl = userData.bitmojiTwoDAvatarUrl;
}
failure:^(NSError *error, BOOL isUserLoggedOut) {
// Handle error
}];
Send 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:
- Swift
- Objective C
let builder = SCSDKUserDataQueryBuilder().withExternalId()
let userDataQuery = builder.build()
// Call fetch API
SCSDKLoginClient.fetchUserData(with:userDataQuery,
success:{ (userData: SCSDKUserData, partialError: Error?) in
let externalId = userData?.externalId;
},
failure:{ (error: Error?, isUserLoggedOut: Bool) in
// Handle error
})
SCSDKUserDataQueryBuilder *builder = [[[SCSDKUserDataQueryBuilder alloc] init] withExternalId];
SCSDKUserDataQuery *userDataQuery = [builder build];
// Call fetch API
[SCSDKLoginClient fetchUserData:userDataQuery
success:^(SCSDKUserData * _Nullable userData, NSError * _Nullable partialError) {
NString *externalId = userData.externalId;
}
failure:^(NSError *error, BOOL isUserLoggedOut) {
// Handle error
}];
Unlink
Unlink 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.
The unlinkCurrentSessionWithCompletion
method has been deprecated.
- Swift
- Objective C
class func clearToken()
+ (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.
Unlink 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
- Objective C
import SCSDKLoginKit
SCSDKLoginClient.unlinkAllSessionsWithCompletion { (success: Bool) in
// Do something
}
#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.
Check a User's Stated Age
Stated Age Check is a mandatory feature of the Login Kit SDK that enforces minimum age restrictions for certain Snap Kit applications and will prevent users who are under the age of 18 from establishing Login Kit connections.
This feature is included in the existing Login Kit integration and does not require additional work from developers. If your app requires Stated Age Check, users will see a non-toggleable "Check your Stated Age" field when connecting to your application.
Due to Snap's Privacy Policy, all apps that are categorized as friend finding or matching will have Stated Age Check toggled during the review state.
Birthday Updates
If your app requires Stated Age Check and a user updates their birthdate in Snapchat after going through the Login Kit connection flow, Snap will disconnect their connection to your app.
Web Login Kit will not work for apps that require Stated Age Check.
Sample Application
Please visit our public GitHub for a sample application using Login Kit on iOS.
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.