Bitmoji Kit

Bitmoji Kit Android 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

  • Android Studio 3.0+
  • Gradle 3.0+
  • Android API Level 19+

Getting started

First, add the following snippet to your build.gradle file:

 repositories {
    maven {
        url "https://storage.googleapis.com/snap-kit-build/maven"
    }
 }

Note: If you have trouble accessing Google (used in the link above), you can use our GitHub Maven repository with the following code block:

repositories {
   maven {
       url "https://raw.githubusercontent.com/Snap-Kit/release-maven/repo"
   }
}

Next, add the snippet below to the dependencies section of your application’s build.gradle file, not the root project’s build.gradle:

 dependencies {
    ...
    implementation([
            'com.snapchat.kit.sdk:bitmoji:1.2.0',
            'com.snapchat.kit.sdk:login:1.2.0',
            'com.snapchat.kit.sdk:core:1.2.0',
    ])
 }

You can also include an optional bitmoji-search library to enable more relevant Bitmoji search results:

 dependencies {
    ...
    implementation([
            ...
            'com.snapchat.kit.sdk:bitmoji-search:1.2.0'
    ])
 }

Finally, add your application’s client ID, redirect URL, and scopes to the appropriate meta-data tags in your application’s AndroidManifest.xml:

 <uses-permission android:name="android.permission.INTERNET" />

 <application ...>
    <meta-data android:name="com.snapchat.kit.sdk.clientId" android:value="your app’s client id" />
    <meta-data android:name="com.snapchat.kit.sdk.redirectUrl" android:value="the url that will handle login completion" />
    <meta-data android:name="com.snapchat.kit.sdk.scopes" android:resource="@array/snap_kit_scopes" /> <!-- This should be a string array of scopes !-->

    ...

    <activity
        android:name="com.snapchat.kit.sdk.SnapKitActivity"
        android:launchMode="singleTask"
        >
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <!--
                Enter the parts of your redirect url below
                e.g. if your redirect url is my-app://abc/xy/z
                    android:scheme="my-app"
                    android:host="abc"
                    android:path="/xy/z"
            !-->
            <data
                android:scheme="the scheme of your redirect url"
                android:host="the host of your redirect url"
                android:path="the path of your redirect url"
                />
        </intent-filter>

    </activity>

    ...
 </application>

Note: By default, Bitmoji Kit uses the dependency versions listed below. If your application shares any of these dependencies, we recommend using similar versions to ensure consistent behavior.

 'com.android.support:appcompat-v7:26.1.0',
 'com.android.support:recyclerview-v7:26.1.0',
 'com.google.dagger:dagger:2.13',
 'com.squareup.okhttp3:okhttp:3.10.0',
 'com.squareup.retrofit2:retrofit:2.4.0',
 'com.squareup.retrofit2:converter-gson:2.4.0',
 'com.squareup.retrofit2:converter-wire:2.4.0',
 'com.squareup.wire:wire-runtime:2.3.0-RC1',
 'com.squareup.picasso:picasso:2.71828',

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

If you are using a Fragment or a FragmentActivity from the Android support library, you may add it to your application as described below:

 getSupportFragmentManager().beginTransaction()
        .replace(R.id.icon_container /* The id of the icon container */, new BitmojiIconFragment())
        .commit();

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

 Bitmoji.fetchAvatarUrl(context, new FetchAvatarUrlCallback() {
        @Override
        public void onSuccess(@Nullable String avatarUrl) {
            // do something
        }

        @Override
        public void onFailure(boolean isNetworkError, int statusCode) {
            // do something
        }
 });

Sticker picker

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

Sticker Picker

To add the sticker picker UI to your app, make sure you are using a Fragment or a FragmentActivity from the Android support library com.android.support:appcompat-v7:26.0.2 and add the code snippet below. This code inserts the sticker picker into a ViewGroup with the ID bitmoji_container in your layout.

 getSupportFragmentManager().beginTransaction()
        .replace(R.id.bitmoji_container /* The id of the sticker picker container */, new BitmojiFragment())
        .commit();

Note: The FragmentActivity that adds the BitmojiFragment must first already implement the OnBitmojiSelectedListener interface. This interface allows the application to be notified whenever a user selects a Bitmoji sticker from the st icker picker.

 @Override
 public void onBitmojiSelected(String imageUrl, Drawable previewDrawable) {
    // do something
 }

The FragmentActivity may also optionally implement the OnBitmojiSearchFocusChangeListener interface, which listens for users entering or exiting the search field:

 @Override
 public void onBitmojiSearchFocusChange(boolean 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:

Fragment fragment = getSupportFragmentManager().findFragmentById(...);
if (fragment instanceof BitmojiFragment) {
    ((BitmojiFragment) fragment).setFriend(friendUserId);
}

Use setSearchText 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).

Fragment fragment = getSupportFragmentManager().findFragmentById(...);
if (fragment instanceof BitmojiFragment) {
    ((BitmojiFragment) fragment).setSearchText(searchText, SEARCH_RESULT_ONLY);
}
Preview search result

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

Bitmoji sticker picker with preview

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

Fragment fragment = getSupportFragmentManager().findFragmentById(...);
if (fragment instanceof BitmojiFragment) {
    ((BitmojiFragment) fragment).attachBitmojiIcon((BitmojiIconFragment) fragment);
}
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.

BitmojiFragment.builder()
        .withShowSearchBar(true)     // show the search bar: defaults to true
        .withShowSearchPills(true)   // show search suggestions: defaults to true
        .withTheme(R.style.my_theme) // 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 (com.snapchat.kit.sdk.bitmoji.R.style.SnapKitBitmojiFragment_Light)
  • Dark (com.snapchat.kit.sdk.bitmoji.R.style.SnapKitBitmojiFragment_Dark)

If you wish to create your own theme, you can define a style in an XML resource file as shown below. Each attribute included acts as an override to the standard theme. You can also build upon the light and dark themes by replacing the parent style with SnapKitBitmojiFragment.Light or SnapKitBitmojiFragment.Dark respectively.

<style name="SnapKitBitmojiFragment" parent="SnapKitBitmojiFragment">
    <item name="snapKitBitmojiBackgroundColor">@color/background_color</item>
    <item name="snapKitBitmojiTitleColor">@color/text_color</item>
    <item name="snapKitBitmojiSubtextColor">@color/subtext_color</item>
    <item name="snapKitBitmojiBorderColor">@color/light_grey</item>
    <item name="snapKitBitmojiSearchColor">@color/primary_color</item>
    <item name="snapKitBitmojiErrorRed">@color/red</item>
    <item name="snapKitBitmojiNavIconColor">@color/dark_grey</item>
    <item name="snapKitBitmojiSearchPillTextColor">@android:color/white</item>
    <item name="snapKitBitmojiSearchPillColorShouldRandomize">true</item>
    <item name="snapKitBitmojiSearchPillShadowColor">@color/shadow</item>
    <!-- an <array> resource of colors -->
    <item name="snapKitBitmojiSearchPillColors">@array/search_pill_colors</item>
</style>

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 search pill differs slightly from the sentiment's assigned color to provide variability. For example, “love” and “kiss” may both share the same sentiment and be colored magenta, but “love” could be a little more purple, whereas “kiss” might be more red. To turn this behavior off, set the attribute snapKitBitmojiSearchPillColorShouldRandomize to false.

Font

To customize the font in the sticker picker, we recommend that your app use Android support library version 26.0 or above. Get started by following the steps below:

  1. Add the font variations that you are using into a fonts resource directory as described in this Android Guide.
  2. Create a font family XML resource in that same directory as shown in this section of the Android Guide.
  3. In your app’s main styles.xml file, modify your app theme to include the font family that you have created. Alternatively, you may add the font family to your sticker picker theme. For example, if your font family resource name is called app_font.xml:
<style name="AppTheme">
    ...
    <item name="android:fontFamily">@font/app_font</item>
</style>

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 that has connected their Snapchat account, call the following:

SnapKit.unlink(context);

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:

String query = "{me{bitmoji{selfie}}}";
SnapLogin.fetchUserData(this, query, null, new FetchUserDataCallback() {
    @Override
    public void onSuccess(@Nullable UserDataResponse userDataResponse) {
        if (userDataResponse == null || userDataResponse.getData() == null) {
            return;
        }

        MeData meData = userDataResponse.getData().getMe();
        if (meData == null) {
            return;
        }

        UserBitmojiData bitmojiData = meData.getBitmojiData();
        if (bitmojiData == null) {
            return;
        }

        String selfieUrl = bitmojiData.getSelfie();
    }

    @Override
    public void onFailure(boolean isNetworkError, int statusCode) {

    }
});

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.

Android Chat

Setup instructions are available in the README.md file.

What’s next


Is this page helpful?
Thanks for your feedback!