Docs
API Reference
For Android
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 Android Snap Kit SDK provides an API in Java, 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, and Bitmoji Kit to get familiar with each. When you're ready to develop Snap Kit functionality in your app, this document provides the Android API components.
We hope you’ll find everything you need. Want to keep up?
- See what’s new in Snap Kit.
- Follow @snapkit for announcements about our SDKs.
App Ads Kit
SAAKConversionEventType
Description
Event types available for App Ads Kit.
Events
SAAKConversionEventType | Can this event be tracked by the developer? |
---|---|
UNKNOWN_EVENT | Yes |
APP_INSTALL | No (This is automatically tracked by the SDK) |
PURCHASE | Yes |
SAVE | Yes |
START_CHECKOUT | Yes |
ADD_CART | Yes |
VIEW_CONTENT | Yes |
ADD_BILLING | Yes |
SIGN_UP | Yes |
SEARCH | Yes |
LEVEL_COMPLETE | Yes |
APP_OPEN | No (This is automatically tracked by the SDK) |
PAGE_VIEW | Yes |
SUBSCRIBE | Yes |
AD_CLICK | Yes |
AD_VIEW | Yes |
COMPLETE_TUTORIAL | Yes |
INVITE | Yes |
LOGIN | Yes |
SHARE | Yes |
RESERVE | Yes |
ACHIEVEMENT_UNLOCKED | Yes |
ADD_TO_WISHLIST | Yes |
SPENT_CREDITS | Yes |
RATE | Yes |
START_TRIAL | Yes |
LIST_VIEW | Yes |
VISITATION | Yes |
CUSTOM_EVENT_1 | Yes |
CUSTOM_EVENT_2 | Yes |
CUSTOM_EVENT_3 | Yes |
CUSTOM_EVENT_4 | Yes |
CUSTOM_EVENT_5 | Yes |
SAAKEventMetadata
Class
The SAAKEventMetadata
class has the following fields, they are all strictly optional:
Property | Description | Type | Required |
---|---|---|---|
itemCategory | Item or category (i.e. International Article Number (EAN) when applicable) | String | No |
itemIds | International Article Number (EAN) when applicable, or another product / category identifier | Array of strings | No |
eventId | UUID from a deeplink click on Snapchat | String | No |
eventDescription | A string description for additional information | String | No |
numberOfItems | Number of items | Number | No |
price | Monetary value of the conversion event in float format. Valid delimiters are “|” “,” “;” | String | No |
currency | Currency in standard ISO 4217 code (ex. EUR, USD, JPY). Required if price is included | String | No |
paymentInfoAvailable | Denotes if the payment information is available. Please pass @YES for yes, @NO for no | Number | No |
transactionId | Transaction ID | String | No |
searchString | The text string that was searched | String | No |
signUpMethod | Sign up method (i.e. Email, In-App, Snapchat, Twitter, etc.) | String | No |
success | Denotes a success. Please pass @YES for yes, @NO for no | Number | No |
level | Level in the game | String | No |
isRetargeting | Whether or not the conversion is from a retargeting campaign. Please pass @YES for yes, @NO for no | Number | No |
email | Email used for the matching attribution event | String | No |
phoneNumber | Phone number used for the matching attribution event | String | No |
limitAdTracking | Denotes if limit ad tracking is on | Boolean | No |
Creative Kit
SnapCreative
Description
This top-level module provides the Creative Kit APIs.
Constructor
1
SnapCreative()
Methods
1
public static SnapCreativeKitApi getApi(Context context)
Getter method for the SnapCreativeKitApi
- Parameters
context
: the activityContext
1
public static SnapMediaFactory getMediaFactory(Context context)
Getter method for the SnapMediaFactory
- Parameters
context
: the activityContext
SnapCreativeKitApi
Description
This is the Creative Kit API module.
Methods
1
public void send(SnapContent content)
Method to send your SnapContent
to Snapchat
- Parameters
content
: theSnapContent
to be sent to Snapchat
1
public void sendWithCompletionHandler(SnapContent content, SnapCreativeKitCompletionCallback callback)
Method to send your SnapContent
to Snapchat with a completion handler indicating if Snapchat was opened
Parameters
content
: theSnapContent
to be sent to Snapchatcallback
: theSnapCreativeKitCompletionCallback
with callbacks when Snapchat is called
SnapCreativeKitCompletionCallback
Description
Callback interface for the CreativeKitApi send method
Methods
1
void onSendSuccess()
Callback called when the user is successfully directed to Snapchat.
1
void onSendFailed(SnapCreativeKitSendError error)
Callback called when an error occurs while attempting to share to Snapchat using Creative Kit.
- Parameters
error
: the error type when sending to Snapchat fails.
SnapMediaFactory
Description
Use this class to create new media files.
Methods
1
public SnapVideoFile getSnapVideoFromFile(java.io.File file)
Factory method to create a SnapVideoFile
instance given a video file
- Parameters
file
: the video file represented as ajava.io.File
- Return value
- The
SnapVideoFile
created from thefile
parameter
- The
- Throws
SnapMediaSizeException
: When media size exceeds 100MBSnapVideoLengthException
: When video length exceeds 60 seconds
1
public SnapPhotoFile getSnapPhotoFromFile(java.io.File file)
Factory method to create a SnapPhotoFile
instance given a photo file
- Parameters
file
: the photo file represented as ajava.io.File
- Return value
- The
SnapPhotoFile
created from thefile
parameter
- The
- Throws
SnapMediaSizeException
: If media size exceeds 100MB
1
public SnapSticker getSnapStickerFromFile(java.io.File file)
Factory method to create a SnapSticker
instance given a sticker file
- Parameters
file
: the sticker file represented as ajava.io.File
- Return value
- The
SnapSticker
created from thefile
parameter
- The
- Throws
SnapStickerSizeException
: If sticker size exceeds 1MB
SnapPhotoFile
Description
This model holds a photo file.
Methods
1
public java.io.File getPhotoFile()
Getter method for the photo file
- Return value
- The
java.io.File
representation of the photo file
- The
SnapPhotoContent
— Extends SnapContent
Description
This is a model of the SnapContent
class for sharing a still image to Snapchat preview.
Constructor
1
SnapPhotoContent(SnapPhotoFile snapPhotoFile)
Constructor for sharing an image to Snapchat
- Parameters
snapPhotoFile
: the image for sharing represented as aSnapPhotoFile
SnapVideoContent
— Extends SnapContent
Description
This is a model of the SnapContent
class for sharing video content to Snapchat preview.
Constructor
1
SnapVideoContent(SnapVideoFile snapVideoFile)
Constructor for sharing video content into Snapchat preview page
SnapSticker
Description
This class holds the sticker data to overlay on the Snap's content.
Methods
1
public void setRotationDegreesClockwise(float rotation)
Setter method for the rotation to apply on the sticker
- Parameters
rotation
: afloat
representing the degrees that the sticker will be rotated clockwise
1
public void setPosX(float positionX)
Setter method for the horizontal position of the sticker
- Parameters
positionX
: afloat
in the range of 0-1 representing the horizontal position of the center of the sticker
1
public void setPosY(float positionY)
Setter method for the vertical position of the sticker
- Parameters
positionY
: afloat
in the range of 0-1 representing the vertical position of the center of the sticker
1
public void setWidth(float width)
Setter method for the width of the sticker, in pixels
- Parameters
width
: afloat
specifying the width of the sticker in pixels
1
public void setHeight(float height)
Setter method for the height of the sticker, in pixels
- Parameters
height
: afloat
specifying the height of the sticker in pixels
1
public void setWidthDp(float widthDp)
Setter method for the width of the sticker, in density-independent pixels.
- Parameters
widthDp
: afloat
specifying the width of the sticker in density-independent pixels.
1
public void setHeightDp(float heightDp)
Setter method for the height of the sticker, in density-independent pixels.
- Parameters
heightDp
: afloat
specifying the height of the sticker in density-independent pixels.
1
public java.io.File getStickerFile()
Getter for the sticker file
- Return value
- The sticker file as a
java.io.File
instance
- The sticker file as a
SnapLiveCameraContent
— Extends SnapContent
Description
This is a model for the SnapContent
class. It links into the camera preview for the Snap.
Constructor
1
SnapLiveCameraContent()
Default constructor for content to share directly into camera page in Snapchat
SnapContent
Description
This is the base SnapContent type. It represents an abstract type that can be shared into Snapchat and contains metadata such as stickers, attachment URL, and caption text properties.
Methods
1
public void setSnapSticker(SnapSticker snapSticker)
Setter method for the sticker to be shared with Snapchat
- Parameters
snapSticker
: theSnapSticker
instance
1
public void setAttachmentUrl(String attachmentUrl)
Setter method to set the attachment URL to link with the Snap
- Parameters
attachmentUrl
: the attachment URLString
1
public void setCaptionText(String captionText)
Setter method for the caption text to overlay on top of the Snap
- Parameters
captionText
: the caption textString
to overlay on top of the Snap
SnapLensContent
Description
A content model for sharing a Lens attachment to the Snapchat camera.
Constructors
1
2
public static SnapLensContent createSnapLensContent(@Nonnull String lensUUID,
@Nullable SnapLensLaunchData snapLensLaunchData)
Deprecated
SnapLensContent(@NonNull String lensId)
Deprecated
SnapLensContent(@NonNull String lensId,
SnapLensLaunchData snapLensLaunchData)
Class Method
1
2
void setSnapLensLaunchData(
SnapLensLaunchData snapLensLaunchData);
Sets the SnapLensLaunchData
for the SnapLensContent
.
- Parameters *
SnapLensLaunchData
to be shared with theSnapLensContent
SnapLensLaunchData.Builder
Description
A builder for SnapLensLaunchData
that models launch data for a Lens.
Constructor
1
SnapLensLaunchData.Builder()
Class Methods
1
Builder addStringKeyPair(String key, String value);
Allows you to add a launch data key-value pair for a string value.
- Parameters * String key and a String value for the launch data pair
1
Builder addNumberKeyPair(String key, Number value);
Allows you to add a launch data key-value pair for a number value.
- Parameters * String key and a Number value for the launch data pair
1
Builder addStringArrayKeyPair(String key, String[] value);
Allows you to add a launch data key-value pair for a String array value.
- Parameters * String key and a String array value for the launch data pair
1
Builder addNumberArrayKeyPair(String key, Number[] value);
Allows you to add a launch data key-value pair for a Number array value.
- Parameters * String key and a Number array value for the launch data pair
Login Kit
SnapLogin
Description
This module handles authentication using Snapchat.
Constructor
1
SnapLogin()
Methods
1
public static View getButton(Context context, ViewGroup container)
Method to get a standard login button to authenticate using Snapchat
Note: Alternatively, you can use AuthTokenManager
directly to start authenticating
- Parameters
context
: the activityContext
container
: the root containerViewGroup
which the login button is inflated into and attached to.
- Return value
- The login button
View
- The login button
1
public static LoginStateController getLoginStateController(Context context)
Getter method for the LoginStateController
- Parameters
context
: the activityContext
- Return value
- the
LoginStateController
for the login through Snapchat
- the
1
public static boolean isUserLoggedIn(Context context)
Getter method to know if user is authenticated using Snapchat and has a valid auth token
- Parameters
context
: the activityContext
- Return value
True
if user is authenticated using Snapchat,False
otherwise
1
public static AuthTokenManager getAuthTokenManager(Context context)
Getter method for the AuthTokenManager
- Parameters
context
: the activityContext
- Return value
- The
AuthTokenManager
instance
- The
1
2
3
4
public static void fetchUserData(Context context,
String query,
String variables,
FetchUserDataCallback callback)
Method to fetch user data based on scopes requested
- Parameters
context
: the activityContext
query
: the GraphQL query to makevariables
: the variables in the GraphQL querycallback
: theFetchUserDataCallback
for when the data is fetched
FetchUserDataCallback
Description
Interface for fetching user data.
Methods
1
void onSuccess(UserDataResponse userDataResponse)
Callback when user data is successfully fetched
- Parameters
userDataResponse
: theUserDataResponse
corresponding to the query
1
void onFailure(boolean isNetworkError, int statusCode)
Callback for when user data request ended in failure
- Parameters
isNetworkError
:True
if requested failed due to a network error,False
otherwisestatusCode
: the status code of the response
AuthTokenManager
Description
The module that manages the user’s auth token credentials.
Methods
1
boolean isUserLoggedIn()
Getter method to know if the AuthTokenManager
has a valid auth token for the user
- Return value
true
if user has a valid access token,false
otherwise
1
boolean hasAccessToScope(String scope)
Determines whether the user has authorized the current session to have access to resources with the requested scope
- Parameters
scope
: The scope (see Understanding Scopes for possible values)
- Return value
true
if the current session has access to resources with the scope,false
otherwise
1
void clearToken()
Method to clear the access token and refresh token locally.
1
void startTokenGrant()
The first step of the OAuth flow; begins the authenticating flow using OAuth
1
@Nullable String getAccessToken();
Getter method for local access token. Note: if this method returns null, the access token may need to be refreshed by using refreshAccessToken
.
- Return value
- Local valid access token string if one exists otherwise null.
1
Void refreshAccessToken(RefreshAccessTokenResult callback);
Asynchronous method for refreshing and obtaining an access token for the current user.
- Parameters
RefreshAccessTokenResult
which will be called to communicate the refresh result.
LoginStateController
Description
This module provides hooks for callbacks on state changes to login.
Methods
1
void addOnLoginStateChangedListener(LoginStateController.OnLoginStateChangedListener listener)
Method to add an OnLoginStateChangedListener
to the LoginStateController
- Parameters
listener
: theOnLoginStateChangedListener
instance to be added to theLoginStateController
1
void removeOnLoginStateChangedListener(LoginStateController.OnLoginStateChangedListener listener)
Method to remove an OnLoginStateChangedListener
from the LoginStateController
- Parameters
listener
: theOnLoginStateChangedListener
instance to be removed from theLoginStateController
1
void addOnLoginStartListener(LoginStateController.OnLoginStartListener listener)
Method to add an OnLoginStartListener
to the LoginStateController
- Parameters
listener
: theOnLoginStartListener
instance to be added to theLoginStateController
1
void removeOnLoginStartListener(LoginStateController.OnLoginStartListener listener)
Method to remove an OnLoginStartListener
from the LoginStateController
- Parameters
listener
: theOnLoginStartListener
instance to be removed from theLoginStateController
LoginStateController.OnLoginStartListener
Description
Interface for when the login request has started after the user has confirmed they want to approve the third party for access to the scopes listed.
Methods
1
void onLoginStart()
Called when the login request has started after the user has confirmed they want to approve the third party for access to the scopes listed
LoginStateController.OnLoginStateChangedListener
Description
Interface for login state change callbacks.
Methods
1
void onLoginSucceeded()
Called when login through Snapchat has succeeded
1
void onLoginFailed()
Called when login through Snapchat failed
1
void onLogout()
Called whenever a user explicitly logs out via clearToken()
or whenever the server returns 401, requiring forced logout
Bitmoji Kit
Bitmoji
Description
This top-level module provides Bitmoji Kit APIs.
Methods
1
public static void fetchAvatarUrl(Context context, FetchAvatarUrlCallback callback)
Makes a network request to fetch the URL for the active user’s Bitmoji avatar icon
- Parameters
context
: the activity or applicationContext
callback
: the callback that will be invoked after either a successful or a failed network request
Example
1 2 3 4 5 6 7 8 9 10 11
Bitmoji.fetchAvatarUrl(context, new FetchAvatarUrlCallback() { @Override public void onSuccess(@Nullable String avatarUrl) { // load the image for the url } @Override public void onFailure(boolean isNetworkError, int statusCode) { // handle the error } });
FetchAvatarUrlCallback
Description
This is the callback for Bitmoji avatar URL fetches made by Bitmoji.fetchAvatarUrl
.
Methods
1
void onSuccess(String avatarUrl)
Called after making a successful network request
- Parameters
avatarUrl
: the URL of the user’s Bitmoji avatar icon, or null if the user does not have Bitmoji
BitmojiFragment
— Extends android.support.v4.app.Fragment
Description
This is the Android Support Library Fragment for the Bitmoji sticker picker.
The FragmentActivity
that adds this Fragment
must first already implement the OnBitmojiSelectedListener
interface. This interface allows the application to be notified whenever a user selects a Bitmoji sticker from the sticker picker.
The FragmentActivity
may also optionally implement the OnBitmojiSearchFocusChangeListener
interface, which listens for users entering or exiting the search field.
Methods
1
public static Builder builder()
- Return value
- An instance of
BitmojiFragment.Builder
- An instance of
1
public void setFriend(String 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
friendUserId
: the external ID of the friend user provided by the app
1
void setSearchText(String searchText)
Method 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).
- Parameters
- The
searchText
: the term that is used to search for Bitmoji stickers
- The
1
void attachBitmojiIcon(BitmojiIconFragment bitmojiIconFragment)
Method 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 setSearchText.
- Parameters
- The
bitmojiIconFragment
: the Bitmoji avatar icon provided by the app to preview sticker picker's search result
- The
BitmojiFragment.Builder
Description
A builder class used to create an instance of BitmojiFragment
with custom configuration.
Methods
1
public Builder withShowSearchBar(boolean showSearchBar)
Method to set the visibility of the sticker picker's search bar.
- Parameters
showSearchBar
: whether the search bar should be shown in the sticker picker
- Return value
this
1
public Builder withShowSearchPills(boolean showSearchPills)
Method to set the visibility of the sticker picker's search suggestions.
- Parameters
showSearchBar
: whether the search suggestions should be shown in the sticker picker
- Return value
this
1
public Builder withTheme(@StyleRes int theme)
Method to set the theme of the sticker picker. See Bitmoji Kit docs for more details.
- Parameters
theme
: the style id of the sticker picker theme
- Return value
this
1
public BitmojiFragment build()
- Return value
- An instance of
BitmojiFragment
with the applied config
- An instance of
OnBitmojiSelectedListener
Description
Your FragmentActivity
that adds the BitmojiFragment
must implement this interface. This allows the FragmentActivity
to be notified whenever a user selects a Bitmoji from the BitmojiFragment
.
Methods
1
void onBitmojiSelected(String imageUrl, Drawable previewDrawable)
Called when the user selects a Bitmoji from the BitmojiFragment
- Parameters
imageUrl
: the URL of the selected BitmojipreviewDrawable
: aDrawable
representing the selected Bitmoji - intended for preview purposes only
OnBitmojiSearchFocusChangeListener
Description
Your FragmentActivity
that adds the BitmojiFragment
may optionally implement this interface. This allows the FragmentActivity
to be notified whenever a user enters or exits the search bar inside the BitmojiFragment
.
Methods
1
void onBitmojiSearchFocusChange(boolean hasFocus)
Called when the user enters or exits the search bar inside the BitmojiFragment
- Parameters
hasFocus
:true
if the user has entered the search bar,false
if the user has exited the search bar
BitmojiIconFragment
— Extends android.support.v4.app.Fragment
Description
This is the Android Support Library Fragment for the Bitmoji 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.