API Reference

For iOS


First time here? Visit the Snap Kit developer portal to add your application, exchange keys, and get set up with the proper API credentials.

The iOS Snap Kit SDK provides an API in Objective-C, organized by kit:

  • Creative: Share media, stickers and other metadata to Snapchat
  • Login: Allow your users to log in using Snapchat credentials and fetch their Bitmoji and identity data
  • Bitmoji: Add a Bitmoji sticker tray to your app so users can communicate visually

We recommend trying the getting started guides for Creative Kit, Login Kit, Bitmoji Kit, and Story Kit to get familiar with each. When you're ready to develop Snap Kit functionality in your app, this document provides the iOS API components.

We hope you’ll find everything you need. Want to keep up?

Creative Kit


SCSDKSnapAPI

Description

This class initiates a deeplink to Snapchat with a SCSDKSnapContent object.

Initializers
// swift

init(content: SCSDKSnapContent)
// objc

- (instancetype _Nonnull)initWithContent:(id<SCSDKSnapContent> _Nonnull)content;
  • Parameters

    • content: A SCSDKSnapContent value to be shared into Snapchat.
  • Return value

    • An initialized SCSDKSnapAPI instance.
  • Raises

    • NSInternalInconsistencyException if content is nil
Instance Methods
// swift

func startSnapping(completionHandler: SCSDKSnapAPICompletionHandler?) -> Void
// objc

- (void)startSnappingWithCompletionHandler:(SCSDKSnapAPICompletionHandler _Nullable)completionHandler;

Initiates sharing into Snapchat.

  • Parameters

    • completionHandler: A SCSDKSnapAPICompletionHandler value describing the behavior after share is complete.
// swift

func cancelSnapping() -> Void
// objc

- (void)cancelSnapping;

Cancels all processes related to sharing into Snapchat.

Callbacks
// swift

typealias SCSDKSnapAPICompletionHandler = (error: Error?) -> Void
// objc

typedef void (^SCSDKSnapAPICompletionHandler)(NSError * _Nullable error);

Callback executed when - (void)startSnappingWithCompletionHandler:(SCSDKSnapAPICompletionHandler _Nullable)completionHandler; completes share.

  • Parameters

    • error: Error describing failures. nil if there is no failure.

SCSDKPhotoSnapContent

Description

SCSDKPhotoSnapContent is an implementation of the SCSDKSnapContent protocol. It provides a way to model a photo Snap for sharing to Snapchat.

Initializers
// swift

init(snapPhoto: SCSDKSnapPhoto)
// objc

- (instancetype _Nonnull)initWithSnapPhoto:(SCSDKSnapPhoto * _Nonnull)snapPhoto;
  • Parameters

    • snapPhoto: An SCSDKSnapPhoto instance.
  • Return value

    • An initialized SCSDKPhotoSnapContent instance.
  • Raises

    • NSInternalInconsistencyException if snapPhoto is nil.
Optional Properties
  • caption: An NSString value to be used as a caption in a Snap.
  • attachmentUrl: An NSString value to be used as an attachment URL in a Snap.
  • sticker: An SCSDKSnapSticker value that models a sticker to be used on a Snap.

SCSDKVideoSnapContent

Description

SCSDKVideoSnapContent is an implementation of the SCSDKSnapContent protocol. It provides a way to model a video Snap for sharing to Snapchat.

Initializers
// swift

init(snapVideo: SCSDKSnapVideo)
// objc

- (instancetype _Nonnull)initWithSnapVideo:(SCSDKSnapVideo * _Nonnull)snapVideo;
  • Parameters

    • snapVideo: An SCSDKSnapVideo instance.
  • Return value

    • An initialized SCSDKVideoSnapContent instance.
  • Raises

    • NSInternalInconsistencyException if snapVideo is nil.
Optional Properties
  • caption: An NSString value to be used as a caption in a Snap.
  • attachmentUrl: An NSString value to be used as an attachment URL in a Snap.
  • sticker: An SCSDKSnapSticker value that models a sticker to be used on a Snap.

SCSDKNoSnapContent

Description

SCSDKNoSnapContent class is an implementation of the SCSDKSnapContent protocol. It provides a way to model a sticker without a photo or video for sharing to Snapchat.

Initializers
// swift

init(caption: String, attachmentUrl: String, sticker: SCSDKSnapSticker)
// objc

- (instancetype _Nonnull)initWithCaption:(NSString * _Nonnull)caption
                           attachmentUrl:(NSString * _Nonnull)attachmentUrl
                                 sticker:(SCSDKSnapSticker * _Nonnull)sticker;
  • Parameters

    • caption: An NSString value to be used as a caption in a Snap.
    • attachmentUrl: An NSString value to be used as an attachment URL in a Snap.
    • sticker: An SCSDKSnapSticker value that models a sticker to be used on a Snap.
  • Return value

    • An initialized SCSDKNoSnapContent instance.
  • Raises

    • NSInternalInconsistencyException if not at least one of caption, attachmentUrl or sticker is set.
Optional Properties

At least one of these must be set, but you have the option of choosing:

  • caption: An NSString value to be used as a caption in a Snap.
  • attachmentUrl: An NSString value to be used as an attachment URL in a Snap.
  • sticker: An SCSDKSnapSticker value that models a sticker to be used on a Snap.

SCSDKSnapPhoto

Description

This class lets you initialize images that users can share to Snapchat.

Initializers
// swift

init(image: UIImage)
// objc

- (instancetype _Nonnull)initWithImage:(UIImage * _Nonnull)image;
  • Parameters

    • image: A UIImage object of content to be shared to Snapchat.
  • Return value

    • An initialized SCSDKSnapPhoto instance.
  • Raises

    • SCSDKSnapPhoto raises an NSInternalInconsistencyException if the image is nil or greater than 15MB.
// swift

init(imageUrl: URL)
// objc

- (instancetype _Nonnull)initWithImageUrl:(NSURL * _Nonnull)imageUrl;
  • Parameters

    • imageUrl: A local NSURL reference to the image being used.
  • Return value

    • An initialized SCSDKSnapPhoto instance.
  • Raises

    • SCSDKSnapPhoto raises a NSInternalInconsistencyException if the image is nil, greater than 15MB, or a file type other than JPEG, JPG, PNG.

SCSDKSnapVideo

Description

This class lets you initialize videos that users can share to Snapchat.

Initializers
// swift

init(videoUrl: URL)
// objc

- (instancetype _Nonnull)initWithVideoUrl:(NSURL * _Nonnull)videoUrl;
  • Parameters

    • videoUrl: A local NSURL reference to the video being used.
  • Return value

    • An initialized SCSCKSnapVideo instance.
  • Raises

    • SCSDKSnapPhoto raises an NSInternalInconsistencyException if the video is nil, greater than 15MB, or a file type other than MOV or MP4.

SCSDKSnapSticker

Description

SCSDKSnapSticker class provides a way to model stickers for overlaying on top of Snaps shared using SnapKit.

Initializers
// swift

init(stickerImage: UIImage)
// objc

- (instancetype)initWithStickerImage:(UIImage *)stickerImage;
  • Parameters

    • stickerImage: A UIImage value to be used as a sticker.
  • Return value

    • An initialized SCSDKSnapSticker instance.
  • Raises

    • NSInternalInconsistencyException if stickerImage is nil or greater than 15MB.
// swift

init(stickerUrl: URL, isAnimated: Bool)
// objc

- (instancetype)initWithStickerUrl:(NSURL *)stickerUrl isAnimated:(BOOL)isAnimated;
  • Parameters

    • stickerURL: A local NSURL pointing to the image to be used for the sticker.
    • isAnimated: A BOOL specifying whether the sticker is animated or not.
  • Return value

    • An initialized SCSDKSnapSticker instance.
  • Raises

    • NSInternalInconsistencyException if stickerURL is nil. If isAnimated is set to NO, NSInternalInconsistencyException when file type is not one of JPEG, JPG or PGN. If isAnimated is set to YES, NSInternalInconsistencyException when file type is not either WebP or GIF.
Optional Properties
  • posX: A CGFloat between 0 and 1 specifying the horizontal position of the center of the sticker relative to the size of the screen. Default value is 0.5
  • posY: A CGFloat between 0 and 1.specifying the vertical position of the center of the sticker relative to the size of the screen. Default value is 0.5
  • width: A CGFloat specifying the absolute width of the sticker in pixels
  • height: CGFloat specifying the absolute height of the sticker in pixels
  • rotation: A CGFloat between 0 and 2pi-radians specifying the rotation of the sticker

Login Kit


SCSDKLoginClient

Description

This class contains all the methods associated for authentication, session control, and information retrieval.


loginFromViewController:completion:

Description

Links into the Snapchat app for authentication. If the user does not have the Snapchat app installed, viewController will open up a Safari webview to Snapchat’s web authentication page.

Class Method
// swift

class func login(from: UIViewController, completion: ((success: Bool, error: Error?) -> Void))
// objc

+ (void)loginFromViewController:(UIViewController *)viewController
                     completion:(void (^)(BOOL success, NSError * _Nullable error))completion;
  • Parameters

    • viewController: UIViewController that shows the in-app auth page.
    • completion: void (^)(BOOL success, NSError * _Nullable error) completion handler for when authorization is fully complete

application:openUrl:options:

Description

This handles deeplink requests from Snapchat. Put this in your AppDelegate’s application:openURL:options: method to handle the deeplink request appropriately.

Class Method
// swift

class func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any]) -> Bool
// objc

+ (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options;
  • Parameters

    • application: application for singleton app object of calling app.
    • url: URL created by Snapchat.
    • options: options for the URL to handle.
  • Return value

    • YES if Snapchat can open the URL.
    • NO if Snapchat cannot open the URL.

unlinkCurrentSessionWithCompletion

Description

Revokes the OAuth session for the user’s device and removes the keychain token on that device.

Class Method
// swift

class func unlinkCurrentSession(completion: ((success: Bool) -> Void)?)
// objc

+ (void)unlinkCurrentSessionWithCompletion:(nullable void (^)(BOOL success))completion;
  • Parameters

    • completion: Block that’s triggered when the session is completely revoked.

unlinkAllSessionsWithCompletion

Description

Revokes the OAuth session for the user regardless of device, and removes the keychain token on the current device. This completely unlinks the users account from your app and Snapchat.

Class Method
// swift

class func unlinkAllSession(completion: ((success: Bool) -> Void)) -> Void
// objc

+ (void)unlinkAllSessionsWithCompletion:(nonnull void (^)(BOOL success))completion;
  • Parameters

    • param : Completion block be triggered when revoking session is finished

fetchUserDataWithQuery

Description
Class Method
// swift

class func fetchUserData(withQuery: String,
    variables: [String : Any]?,
    success: SCOAuth2GetResourcesSuccessCompletionBlock,
    failure: SCOAuth2GetResourcesFailureCompletionBlock) -> Void
// objc

+ (void)fetchUserDataWithQuery:(nonnull NSString *)query
                     variables:(nullable NSDictionary<NSString *, id> *)variables
                       success:(nonnull SCOAuth2GetResourcesSuccessCompletionBlock)success
                       failure:(nonnull SCOAuth2GetResourcesFailureCompletionBlock)failure;
  • Parameters

    • query: GraphQL query to fetch user data.
    • variables: Dynamic arguments for query.
    • success: Success block when fetch data succeed.
    • failure: Failure block when fetch data failed.

hasAccessToScope:

// swift

class func hasAccess(toScope: String) -> Bool
// objc

+ (BOOL)hasAccessToScope:(nonnull NSString *)scope;
  • Parameters

  • Return value

    • YES if the current session has access to resources with the scope, NO otherwise

addLoginStatusObserver

Description

Add an observer to receive updates to the user's login status.

Class Method
// swift

class func addLoginStatusObserver(_: SCSDKLoginStatusObserver)
// objc

+ (void)addLoginStatusObserver:(id<SCSDKLoginStatusObserver>)observer;
  • Parameters

    • observer: The object that will receive updates.

removeLoginStatusObserver

Description

Remove an observer to stop receiving updates to the user's login status.

Class Method
// swift

class func removeLoginStatusObserver(_: SCSDKLoginStatusObserver)
// objc

+ (void)removeLoginStatusObserver:(id<SCSDKLoginStatusObserver>)observer;
  • Parameters

    • observer: The object currently receiving updates.

SCSDKLoginStatusObserver

Description

This is a protocol for observing all changes that occur for a user's login status. Notifications will always occur on the main queue.

Methods
// swift

func scsdkLoginLinkDidSucceed()
// objc

- (void)scsdkLoginLinkDidSucceed;

(Optional) Called whenever a user successfully authorizes with their Snapchat account.

// swift

func scsdkLoginLinkDidFail()
// objc

- (void)scsdkLoginLinkDidFail;

(Optional) Called whenever a user's authorization process fails.

// swift

func scsdkLoginDidUnlink()
// objc

- (void)scsdkLoginDidUnlink;

(Optional) Called whenever a user either explicitly unlinks their Snapchat account, or access to the user's account is revoked.

Callbacks


SCOAuth2GetResourcesSuccessCompletionBlock

Description

This callback executes when you successfully get resources from Snapchat server.

Completion Block
// swift

typealias SCOAuth2GetResourcesFailureCompletionBlock = (resources: Dictionary?) -> Void
// objc

typedef void(^SCOAuth2GetResourcesFailureCompletionBlock)(NSDictionary * _Nullable resources);
  • Parameters

    • resources: Resources that contain user data.

SCOAuth2GetResourcesFailureCompletionBlock

Description

Callback error method.

Completion Block
// swift

typealias SCOAuth2GetResourcesFailureCompletionBlock = (error: Error?, isUserLoggedOut: Bool) -> Void
// objc

typedef void(^SCOAuth2GetResourcesFailureCompletionBlock)(NSError * _Nullable error, BOOL isUserLoggedOut);
  • Parameters

    • error : provided by the callback method that happened when fetch data from resource server
    • isUserLoggedOut : set to YES if the connection between your app and Snapchat is broken or user is not logged in to your app using Snapchat. Set to NO if other errors occur while fetching data from Snapchat.

Bitmoji Kit


SCSDKBitmojiClient

Description

Fetches the user’s Bitmoji.

Class Methods
// swift

class func fetchAvatarUrl(_ completion: ((avatarURL: String?, error: Error?) -> Void)) -> Void
// objc

+ (void)fetchAvatarUrlWithCompletion:(void(^)(NSString *avatarURL, NSError *error))completion;

This method makes a network request to fetch the URL for the active user’s Bitmoji avatar icon.

  • Parameters

    • completion is a void(^)(NSString *avatarURL, NSError *error). This is the block invoked after either a successful or a failed network request.
    • If the network request fails, the error is not nil.
    • If the network request succeeds, the error is always nil. avatarURL contains the URL for the user’s avatar icon.
Examples
// swift

import SCSDKBitmojiKit

SCSDKBitmojiclient.fetchAvatarURL({ (avatarURL: String?, error: Error?) in
    if (error) {
        // handle the error
    } else {
        // load the image
    }
})
// objc

#import <SCSDKBitmojiKit/SCSDKBitmojiKit.h>

[SCSDKBitmojiClient fetchAvatarURLWithCompletion:^(NSString *avatarURL, NSError *error) {
    if (error) {
        // handle the error
    } else {
        // load the image
    }
}];

SCSDKBitmojiStickerPickerViewControllerDelegate

The delegate for the SCSDKBitmojiStickerPickerViewController must implement this protocol in order to get notified whenever a user selects a Bitmoji and whenever a user enters or exits the search bar.

Instance Methods
// swift

func bitmojiStickerPickerViewController(_ stickerPickerViewController: SCSDKBitmojiStickerPickerViewController,
                                        didSelectBitmojiWithURL bitmojiURL: String,
                                        image: UIImage?) -> Void
// objc

- (void)bitmojiStickerPickerViewController:(SCSDKBitmojiStickerPickerViewController *)stickerPickerViewController 
                   didSelectBitmojiWithURL:(NSString *)bitmojiURL
                                     image:(UIImage *)image;

This method is called when the user selects a Bitmoji from the BitmojiFragment.

  • Parameters

    • bitmojiStickerPickerViewController is an SCSDKBitmojiStickerPickerViewController for the sticker picker.
    • bitmojiURL is an NSString and is the URL of the selected Bitmoji.
    • image is a UIImage representing the selected Bitmoji. This is intended for previewing purposes only.
// swift

func bitmojiStickerPickerViewController(_ stickerPickerViewController: SCSDKBitmojiStickerPickerViewController,
    searchFieldFocusDidChangeWithFocus hasFocus: Bool) -> Void
// objc

- (void)bitmojiStickerPickerViewController:(SCSDKBitmojiStickerPickerViewController *)stickerPickerViewController searchFieldFocusDidChangeWithFocus:(BOOL)hasFocus;

This method is optional. It is called when the user enters or exits the search bar inside the sticker picker.

  • Parameters

    • bitmojiStickerPickerViewController is an SCSDKBitmojiStickerPickerViewController for the sticker picker.
    • bitmojiURL is a BOOL that’s true if the user enters the search bar, false if the user exits the search bar.

SCSDKBitmojiStickerPickerViewController

Extends UIViewController. This is the UIViewController for the Bitmoji sticker picker.

Methods
// swift

weak var delegate: SCSDKBitmojiStickerPickerViewControllerDelegate?
// objc

@property (weak, nullable) id<SCSDKBitmojiStickerPickerViewControllerDelegate> delegate;

This delegate will be notified whenever a user selects a Bitmoji and whenever a user either enters or exits the search bar in the sticker picker view. See SCSDKBitmojiStickerPickerViewControllerDelegate for more details.

`swift` // swift

func setFriendUserId(friendUserId: String) -> Void

```objc
// objc

- (void)setFriendUserId:(nonnull NSString *)friendUserId;

Method to specify a friend user to feature in Bitmojis. The sticker picker will include Bitmojis co-starring the current user and the provided friend user. The friend will only appear if they have granted the app access to their Bitmoji avatar as well.

  • Parameters

    • The friendUserId: the external ID of the friend user provided by the app

SCSDKBitmojiIconView

Extends UIView. This is the UIView for the Bitmoji avatar icon.

The avatar icon is an image of your user that automatically refreshes to display the latest version of their avatar in your app. If the user is not logged in or does not have a Bitmoji, the element simply shows the Bitmoji logo.