Bitmoji Kit

Bitmoji Kit brings a native Bitmoji experience into your app. Users can access their Bitmoji sticker library in a tap to make messages more fun, more expressive, and truly personal.

Users must be logged into Snapchat to use Bitmoji Kit’s features in your app.

Please ensure your app follows our Bitmoji Kit Integration Checklist and Bitmoji Brand Guidelines.

iOS

Bitmoji Kit iOS gives you access to two Bitmoji features, the avatar icon and sticker picker. The avatar icon gives users a familiar visual identity within your app. The sticker picker lets users browse, search, and send Bitmojis.

Requirements

  • Xcode version 9.0+
  • iOS version 10.0+
  • PINCache 2.3 — See instructions to add to your build process

Getting started

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

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

  • SCSDKClientId (string): Your application’s client ID
  • SCSDKRedirectUrl (string): The URL that will handle and complete login requests
  • SCSDKScopes (string-array): The scopes your application will request
  • LSApplicationQueriesSchemes (string-array): Must contain snapchat, bitmoji-sdk, and itms-apps
  • CFBundleURLSchemes (string-array): Must contain your redirect URL’s scheme — so if your redirect URL is my-app://abc/xy/z, this field would contain my-app

To handle login requests properly, add the following to your UIApplicationDelegate:

// swift

import SCSDKLoginKit

func application(_ app: UIApplication,
                 open url: URL,
                 options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
    let handled = SCSDKLoginClient.application(app, open: url, options: options)
    ...
}
// objc

#import <SCSDKLoginKit/SCSDKLoginKit.h>

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

Features

Avatar icon

The avatar icon is an image of your Bitmoji avatar in your app. If the user is not logged in or does not have a Bitmoji, the element simply shows the Bitmoji logo.

Bitmoji Avatar

To implement the avatar icon, add an iconView:

// swift

import SCSDKBitmojiKit

let iconView = SCSDKBitmojiIconView()
// objc

#import <SCSDKBitmojiKit/SCSDKBitmojiKit.h>

UIView *iconView = [[SCSDKBitmojiIconView alloc] init];

You can also retrieve the URL of a user’s Bitmoji profile with the following snippet:

// swift

import SCSDKBitmojiKit

SCSDKBitmojiClient.fetchAvatarURL { (avatarURL: String?, error: NSError?) in
    // do something
}
// objc

#import <SCSDKBitmojiKit/SCSDKBitmojiKit.h>

[SCSDKBitmojiClient fetchAvatarURLWithCompletion:^(NSString *avatarURL, NSError *error) {
    // do something
}];

Sticker picker

The sticker picker is a visual interface that allows users to select Bitmoji stickers from the latest sticker catalog. Users can browse and search through the extensive Bitmoji library with the integrated UI.

Sticker Picker

To add the sticker picker UI, create a sticker picker view, and add a delegate to be notified whenever a user selects a sticker:

// swift

import SCSDKBitmojiKit

override func viewDidLoad() {
   super.viewDidLoad()
   ...
   let stickerPickerVC = SCSDKBitmojiStickerPickerViewController()
   stickerPickerVC.delegate = self

   addChildViewController(stickerPickerVC)
   view.addSubview(stickerPickerVC.view)
   stickerPickerVC.didMove(toParentViewController: self)
   ...
}

func bitmojiStickerPickerViewController(_ stickerPickerViewController: SCSDKBitmojiStickerPickerView,
                                        didSelectBitmojiWithURL bitmojiURL: String,
                                        image: UIImage?) {
   // do something
}

// Optional delegate method for listening to search field
// focus changes
func bitmojiStickerPickerViewController(_ stickerPickerViewController: SCSDKBitmojiStickerPickerView,
                                        searchFieldFocusDidChangeWithFocus hasFocus: Bool) {
   // do something
}
// objc

#import <SCSDKBitmojiKit/SCSDKBitmojiKit.h>

- (void)viewDidLoad
{
   [super viewDidLoad];
   ...
   SCSDKBitmojiStickerPickerViewController *stickerPickerVC = [[SCSDKBitmojiStickerPickerViewController alloc] init];
   stickerPickerVC.delegate = self;

   [self addChildViewController:stickerPickerVC];
   [self.view addSubview:stickerPickerVC];
   [stickerPickerVC didMoveToParentViewController:self];
   ...
}

- (void)bitmojiStickerPickerViewController:(SCSDKBitmojiStickerPickerViewController *)stickerPickerView
                   didSelectBitmojiWithURL:(NSString *)bitmojiURL
                                     image:(UIImage *)image
{
   // do something
}

// Optional delegate method for listening to search field
// focus changes
- (void)bitmojiStickerPickerViewController:(SCSDKBitmojiStickerPickerViewController *)stickerPickerView
        searchFieldFocusDidChangeWithFocus:(BOOL)hasFocus
{
   // do something
}
Friendmoji

To enable Friendmojis, Bitmojis co-starring the current user and a friend, pass an external ID of another user to the sticker picker view:

// swift

import SCSDKBitmojiKit

override func viewDidLoad() {
   super.viewDidLoad()
   ...
   let friendUserId = ...
   let stickerPickerVC = SCSDKBitmojiStickerPickerViewController()
   stickerPickerVC.delegate = self
   stickerPickerVC.setFriendUserId(friendUserId)
   ...
}
// objc

#import <SCSDKBitmojiKit/SCSDKBitmojiKit.h>

- (void)viewDidLoad
{
   [super viewDidLoad];
   ...
   SCSDKBitmojiStickerPickerViewController *stickerPickerVC = [[SCSDKBitmojiStickerPickerViewController alloc] init];
   NSString *friendUserId = ...
   [stickerPickerVC setFriendUserId:friendUserId];

Use setSearchTerm to seed the sticker picker's search state (i.e. passing in the search term "Friday" will update the sticker picker with Friday-related Bitmoji stickers).

// swift

import SCSDKBitmojiKit

stickerPickerVC.setSearchTerm("Friday")
// objc

#import <SCSDKBitmojiKit/SCSDKBitmojiKit.h>

[stickerPickerVC setSearchTerm:@"Friday"];
Preview search result

Use attachBitmojiIcon to register a Bitmoji avatar icon to listen to Bitmoji sticker picker's search state. By linking the Bitmoji avatar icon with the Bitmoji sticker picker, the avatar icon will display a preview of the first search result in the sticker picker every time the search term is updated. This can be used to provide users with a preview of the available Bitmoji stickers when combined with setSearchTerm.

Bitmoji sticker picker with preview

To link the avatar icon with the sticker picker, use SCSDKBitmojiStickerPickerViewController.attachBitmojiIcon, as shown below:

// swift

import SCSDKBitmojiKit

stickerPickerVC.attachBitmojiIcon(iconView)
// objc

#import <SCSDKBitmojiKit/SCSDKBitmojiKit.h>

[stickerPickerVC attachBitmojiIcon:iconView];
Styling

The Bitmoji sticker picker offers several styling options to help the widget match the look and feel of your app. These options can be set as shown below.

//objc

SCSDKBitmojiStickerPickerConfigBuilder *configBuilder = [[SCSDKBitmojiStickerPickerConfigBuilder alloc] init];
[configBuilder withShowSearchBar:YES];     // show the search bar: defaults to true
[configBuilder withShowSearchPills:YES];   // show search suggestions: defaults to true
// the theme for adjusting various colors, more details below
[configBuilder withTheme:SCSDKBitmojiStickerPickerTheme.lightTheme];

[SCSDKBitmojiStickerPickerViewController alloc] initWithConfig:[configBuilder build]];
//swift

SCSDKBitmojiStickerPickerViewController(
    config: SCSDKBitmojiStickerPickerConfigBuilder()
        .withShowSearchBar(true)     // show the search bar: defaults to true
        .withShowSearchPills(true)   // show search suggestions: defaults to true
        .withTheme(.light)           // the theme for adjusting various colors, more details below
        .build())

Note: A search pill refers to a colored and oblong block that each search term appears in when search results and default suggestions are displayed.

Theme

Themes can be used to change the colors of many sections of the sticker picker. Bitmoji Kit provides two themes (in addition to the default styling) out of the box:

  • Light (SCSDKBitmojiStickerPickerTheme.lightTheme)
  • Dark (SCSDKBitmojiStickerPickerTheme.darkTheme)

If you wish to create your own theme, you can create one using SCSDKBitmojiStickerPickerThemeBuilder as shown below. Each builder method acts as an override to the standard theme. You can also build upon the built-in themes by using the toBuilder method.

// objc
SCSDKBitmojiStickerPickerThemeBuilder *builder = [[SCSDKBitmojiStickerPickerThemeBuilder alloc] init];

[builder withBackgroundColor:UIColor.whiteColor];
[builder withTitleTextColor:UIColor.blackColor];
[builder withSubtextColor:UIColor.grayColor];
[builder withBorderColor:UIColor.lightGrayColor];
[builder withErrorRed:UIColor.redColor];
[builder withSearchColor:UIColor.blueColor];
[builder withNavIconColor:UIColor.darkGrayColor];
[builder withSearchPillTextColor:UIColor.whiteColor];
[builder withSearchPillColors:@[UIColor.greenColor, UIColor.cyanColor]];
[builder withSearchPillShadowColor:[UIColor colorWithWhite:0.0f alpha:0.04f]];
[builder withShouldRandomizeSearchPillColors:YES];

[builder build];
// swift
SCSDKBitmojiStickerPickerThemeBuilder()
    .withBackgroundColor(.white)
    .withTitleTextColor(.black)
    .withSubtextColor(.gray)
    .withBorderColor(.lightGray)
    .withErrorRed(.red)
    .withSearchColor(.blue)
    .withNavIconColor(.darkGray)
    .withSearchPillTextColor(.white)
    .withSearchPillColors([.green, .cyan])
    .withSearchPillShadowColor(UIColor(white:0.0, alpha:0.04))
    .withShouldRandomizeSearchPillColors(true)
    .build()

You can specify 1-6 search pill colors. Additionally, the index of each color in the array corresponds to a sentiment for a search term, provided in the order shown below.

  1. Greetings
  2. Affection
  3. Positive
  4. Negative
  5. Occasions
  6. Other (any term that doesn't belong in the categories above)

If fewer than 6 colors are provided, then the array of colors will be repeated so that each sentiment has a color.

By default, the color of each term is randomized to provide more color variability. To turn this behavior off, pass the value false/NO to withShouldRandomizeSearchPillColors.

Font

To customize the font in the sticker picker, add the following lines to your app's Info.plist:

<key>SCSDKFonts</key>
<dict>
  <key>regular</key>
  <string>MyAppFont-Medium<!-- Replace with your app's font name --></string>
  <key>bold</key>
  <string>MyAppFont-Bold<!-- Replace with your app's bold font name --></string>
</dict>

Unlinking

To remove a user’s Bitmoji content currently displayed in the app (either in avatar icons or in the sticker picker), unlink the user’s Snapchat account from your app.

To unlink a user who has connected their Snapchat account to your app, call the following snippet:

// swift

import SCSDKLoginKit

SCSDKLoginClient.unlinkCurrentSession { success in
    // do something
}
// objc

#import <SCSDKLoginKit/SCSDKLoginKit.h>

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

That’s it! You just learned how to integrate the Bitmoji experience into your app, and how to unlink if needed.

Selfie

The selfie is a unique static URL to an image of your Bitmoji avatar for your app. The image content updates when your avatar changes. The selfie URL can be stored indefinitely by developers and then used anywhere in your app. An error status code is returned if the user has not granted Bitmoji avatar permissions to your app.

Use the SCSDKLoginClient to fetch the Bitmoji selfie URL:

// swift

let graphQLQuery = "{me{bitmoji{selfie}}}"

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 }

  var bitmojiSelfieUrl: String?
  if let bitmoji = me["bitmoji"] as? [String: Any] {
    bitmojiSelfieUrl = bitmoji["selfie"] as? String
  }
}, failure: { (error: Error?, isUserLoggedOut: Bool) in
	// handle error
})
// objc

NSString *graphQLQuery = @"{me{bitmoji{selfie}}}";

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

Reference app

Need to see an example? Find our reference application on GitHub to see how the library can be integrated in a messaging app. Setup instructions are available in the README.md file.

iOS Chat

What’s next


PreviousLogin Kit Web
NextBitmoji Kit Android
Is this page helpful?
Thanks for your feedback!