Docs

Ad Kit Android

Ad Kit allows developers to monetize their app with the Snap Audience Network. This feature is not available to all developers. Please apply for access here.


Requirements


Important Information

Testing Outside the US
  • Confirm the tester is using a US-based proxy/VPN.
  • Confirm the tester is using a device that does not have Snapchat installed.
    • If the device ever had Snapchat installed, the tester must rotate the IDFA.
  • If Snapchat is currently installed, delete Snapchat and rotate the IDFA.
Troubleshooting
  • We have a several validations in place. The most notable, is the US-based IP check.
  • The SDK will not re-attempt initialization for 24h after a failure due to ineligibility.
    • You can avoid the 24h delay by deleting the test app and reinstalling.
  • Outside the US? You'll need to VPN to a US-based ip address to successfully initialize the SDK
  • The recommended test plan is:
    • Delete Snapchat if it's installed on the device.
    • Rotate the IDFA.
    • Install the test app with the SDK.
    • VPN to US-based IP address before trying to initialize.
  • Still having trouble? Please reach out to your Partner Manager or adkit-support@snapchat.com
Test Ad Slot IDs

While building your integration, please test your code only with our designated Test Ad Slot IDs:

Test Slot IDExpected Ad ResponseFormat
01aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns App Install Video AdInterstitial
02aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns App Install Image AdInterstitial
03aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Display Video AdInterstitial
04aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Display Image AdInterstitial
05aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Web View Video AdInterstitial
06aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Web View Image AdInterstitial
07aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaaReturns Video Ad with Small FormatsRewarded Video Banner Medium Rectangle
90ffffff-ffff-ffff-ffff-ffffffffffffNo Ad was returned from the server {SUCCESS with no-fill ad response (no ad could be found)}

Getting Started

Step 1: Create an App via Snap Kit

To get started with Ad Kit, you will need to create an app via Snap Kit and generate an app ID.

In order to create an app, you need a Snapchat account. If you are new to Snapchat, download Snapchat on your device and create a new account. Make sure to link an email to your account, as it is required to log in to the Snap Kit portal.

Once you have a Snapchat account, log in to the Snap Kit portal and click on the highlighted icon to add your application:

Then, name your application and save. Note: If you are only integrating Ad Kit to your app, toggle off Bitmoji avatar and Story Studio API.

Once you have created your app, your snapKitAppId will show up as a string in the URL, i.e. 8944b384-432f-4075-92e0-fe4b8682a0aa. Copy and save this value.

Step 2: Import the SDK

The Ad Kit SDK is publicly available on the Maven Central Repository and can be included as shown below:

1buildscript {
2    repositories {
3        maven { url 'http://repo1.maven.org/maven2' }
4    }
5}
6repositories {
7    mavenCentral()
8}
9
10dependencies {
11    implementation "com.snap.adkit:adkit:1.2.0"
12}

Ad Kit requires the following additional dependencies defined in your build.gradle (This list might grow in the future):

1dependencies {
2    implementation 'androidx.lifecycle:lifecycle-common:2.0.0'
3    implementation 'androidx.appcompat:appcompat:1.0.0'
4    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
5    implementation 'androidx.media:media:1.0.0'
6    implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.70'
7    implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
8    implementation 'com.squareup.okhttp3:okhttp:3.9.0'
9    implementation 'com.google.android.exoplayer:exoplayer-core:2.11.3'
10    implementation 'com.squareup.picasso:picasso:2.71828'
11}

Step 3: Initialize the SDK

In your own app application onCreate(), start the Ad Kit application lifecycle and initialize SnapAdKit as follows:

1override fun onCreate() {
2    super.onCreate()
3
4    AdKitApplication.init(getApplicationContext()) // Provide the application context here
5    val snapAdKit = AdKitApplication.getSnapAdKit()
6    snapAdKit.init()
7}

Register your app id with AdKit SDK (this must be already whitelisted by Snap) and provide an optional location parameter:

1snapAdKit.register(<app_id: String>, <location: Location?>)

While using the SDK, if the registration times out, you will have to re-register, but you will not have to re-initialize.

To listen for events, create an event listener by implementing AdsExternalEventListener. Use a singleton instance of this listener. The onEvent() method provides you the event fired along with the slotId of the ad it was fired for. The full list of events is listed here. Then, setup the SDK to listen for these events.

1class InterstitialEventListener : AdsExternalEventListener {
2  override fun onEvent(event: SnapAdKitEvent, slotId: String?) {
3    when (event) {
4      is SnapAdInitSucceeded -> {
5        // Handle event
6      }
7      // Handle other events here
8      else -> {
9        // Handle generic case
10      }
11  }
12}
13
14// Get or create singleton instance of your custom event listener
15val listener = InterstitialEventListener()
16
17// Pass it to SnapAdKit
18snapAdKit.setupListener(listener)

Step 4: Load an Ad (Interstitial / Rewarded)
Step 4.1 Load an Interstitial Ad

To request for an interstitial ad (this will make the ad request and keep the ad in memory):

1snapAdKit.loadInterstitial(<slotId>: String, null)
Step 4.2 Load a Rewarded Ad

To request for a rewarded ad (this will make the ad request and keep the ad in memory):

1snapAdKit.loadRewarded(<slotId>: String, null)

Rewarded ads fire a special event when the reward has been earned: SnapAdRewardedEarned. This can be intercepted in your implementation of SnapAdEventListener.

In the past, Ad Kit could only load one ad at a time into memory. Now, you can load several ads into memory and play them one by one. For example, you can load an interstitial ad with various slotIDs, then load a few rewarded ads; then, you'll be able to play interstitial ads or rewarded ads as you please, as long as the requested slotID has an ad loaded in memory.


Step 5: Play an Ad

In your fragment or activity, play the ad as follows. This will bring up a new activity showing the ad content:

1snapAdKit.playAd(<slotId>: String)

Step 6: Clean Up Resources

Override your application class onDestroy() method to free up resources as follows. (Note that if you don’t do this in the application class but in fragment or activity, you will need to call snapAdKit.init() again in order for SnapAdKit to work properly).

1override fun onDestroy() {
2    super.onDestroy()
3    snapAdKit.destroy()
4}

Step 7: Load an Ad (Banner)
Step 7.1: Add to Layout

First, add BannerView to the layout of your Activity or Fragment. You can do this in the layout XML or programmatically.

In layout XML:

1# my_activity.xml
2...
3    <com.snap.adkit.external.BannerView
4        android:id="@+id/banner_ad"
5        android:layout_width="wrap_content"
6        android:layout_height="wrap_content"
7        app:layout_constraintBottom_toBottomOf="parent"
8        app:layout_constraintStart_toStartOf="parent"
9        app:layout_constraintEnd_toEndOf="parent"/>
10
11...

Programmatically:

1val bannerAd = BannerView(this)
Step 7.2: Set Up BannerView

Now, set the SnapAdSize for the BannerView as well as a slotId for the ad request.

At the moment, only SnapAdSize.BANNER and SnapAdSize.MEDIUM_RECTANGLE are supported.

1bannerAd.setAdSize(SnapAdSize.BANNER)
2bannerAd.updateSlotId(<slotId: String>) // set the slotId of the ad to request
Step 7.3: Listen For Events

The listener attached to SnapAdKit will not return ad load, visibility, or attributions events for banner ads. Instead, attach a listener to the ad as such:

1// Implement SnapAdEventListener and attach to the ad view to get banner ad events
2bannerAd.setupListener(<listener: SnapAdEventListener>)

Banner events are: SnapAdLoadSucceeded, SnapAdLoadFailed, SnapAdVisible, SnapAdClicked, SnapBannerAdImpressionRecorded (this event is unique to the banner as impression).

Step 7.4: Load the Ad

Now, you're ready to load the ad:

1bannerAd.loadAd(<slotId>: String, null)

If you want to delay adding the BannerView to your activity or fragment until you are sure the ad has loaded, you can do so in the onEvent() method of your listener:

1bannerAd.setupListener(object : SnapAdEventListener {
2    override fun onEvent(event: SnapAdKitEvent, slotId: String?) {
3        when (event) {
4                is SnapAdLoadSucceeded-> {
5                    // If you are reusing the banner ad,
6                    // first detach it from your activity/fragment before reattaching
7                    container.removeView(bannerAd)
8                    // Attach the banner ad to the container view
9                    // in your activity/fragment
10                    container.addView(bannerAd)
11                    // Handle event
12                }
13                ...
14    }
15}
Step 8: Clean Up Resources

To avoid memeory leaks in your app, please call the following line once you are done using your instance of BannerView. Do not call this if you plan to reuse the same instance. For example:

1// in your activity
2override fun onDestroy() {
3    bannerAd.destroy()
4    super.onDestroy()
5}
Banner Track

The impression track for banner ads is recroded when 50% of the view has been in view continuously for 1 second. Just like other impression tracks, we will fire SnapAdImpressionHappened when this impression is recorded.


Events

The following events are emitted by the SDK and can be handled within the fun onEvent(event: SnapAdKitEvent) method in your custom event listener overriding AdsExternalEventListener described in Step 2 above. These events extend the sealed class SnapAdKitEvent.

EventDescription
SnapAdInitSucceededSDK initialization succeeded
SnapAdInitFailed(val throwable: Throwable)SDK initialization failed
SnapAdLoadSucceededSuccessfully loaded ad
SnapAdLoadFailed(val throwable: Throwable)Failed to load ad
SnapAdVisibleAd has become visible
SnapAdClickedAd received a click
SnapAdImpressionHappenedAd impression has been recorded
SnapAdDismissedAd was dismissed
SnapAdRewardedEarnedReward was earned (for rewarded ads only)
SnapBannerAdImpressionRecordedBanner ad impression was recorded (for banner ads only)

Logging

We internally log essential information in logcat. You can search for SnapAdKit or InterstitialAdsActivity to find those logs and to help debug any issues.


Possible Integration Issues

If your project runs on an Android Gradle Plugin (AGP) version number that is below 4.0.0-alpha07, you may see the following build failure:

Caused by:java.lang.RuntimeException: Failed to transform '..libs/snap-adkit.aar' using Jetifier. Reason: StringIndexOutOfBoundsException, message: String index out of range: -2.

You may also have to do this if your project is written in Java instead of Kotlin.

Jetifier is supposed to work on third-party libraries that do not yet support AndroidX. However, if a library has already been updated to support AndroidX (which Ad Kit has), or if it is not using AndroidX / support libraries at all, then it is not necessary to run Jetifier to convert it, and doing so may even result in incorrect rewritten binaries. AGP versions below 4.0.0-alpha07 attempt to Jetify libraries that support AndroidX, causing the above failure.

To fix this, in your gradle.properties, add Ad Kit to the Jetifier blacklist so it is not Jetified. Once you upgrade AGP to at or above 4.0.0-alpha07, you may remove this line:

1android.jetifier.blacklist=snap-adkit

If you still face the same issue, please update the grade-wrapper version. In the /gradle/wrapper/gradle-wrapper.properties folder, update the distributionUrl to 6.1.1 or higher.

1distributionUrl=https\://services.gradle.org/distributions/gradle-6.1.1-all.zip (https://snap.slack.com//services.gradle.org/distributions/gradle-6.1.1-all.zip)