Ad integration

shortkit integrates with Google IMA SDK to deliver native in-feed video ads that match your app’s look and feel.

Overview

The ad integration architecture:

SDK requests ad: Feed controller determines when an ad slot is due
IMA SDK fetches ad: Requests ad from Google Ad Manager
Native rendering: SDK renders ad in its own feed card with your styling
Tracking compliance: SDK fires all required VAST tracking events

Account setup

Option 1: Self-managed

Use your own Google Ad Manager account:

Get your GAM credentials

From your Google Ad Manager account:

Network code
Ad unit ID for in-feed video

Configure in Admin Portal

Go to Ads → Configuration
Select Self-managed
Enter your network code and ad unit ID
Click Verify Connection

Map content categories

Go to Ads → Configuration → Categories
Map your content tags to IAB categories
This enables targeted ad delivery

Option 2: Platform-managed

Let shortkit handle ad operations:

Go to Ads → Configuration
Select Platform-managed
Complete enrollment form
Our team sets up your inventory
View revenue in the Ads dashboard

Platform-managed benefits:

Optimized fill rates and CPMs
No ad ops expertise required
Aggregate data improves targeting
Dedicated support

SDK configuration

Enable ads in your SDK configuration:

iOS
Android
React Native
Web

let config = ShortkitConfig(
    // ... other config
    ads: AdsConfig(
        enabled: true,
        frequency: .countBased(interval: 5, firstAdAfter: 3)
    )
)

val config = ShortkitConfig(
    // ... other config
    ads = AdsConfig(
        enabled = true,
        frequency = AdFrequency.CountBased(interval = 5, firstAdAfter = 3)
    )
)

const config = {
  // ... other config
  ads: {
    enabled: true,
    frequency: {
      mode: 'count',
      interval: 5,
      firstAdAfter: 3
    }
  }
};

const config = {
  // ... other config
  ads: {
    enabled: true,
    frequency: {
      mode: 'count',
      interval: 5,
      firstAdAfter: 3
    }
  }
};

Ad frequency modes

Count-based

Show an ad every N content videos:

ads: {
  frequency: {
    mode: 'count',
    interval: 5,      // Ad every 5 videos
    firstAdAfter: 3   // No ads until 3rd video
  }
}

Time-based

Show an ad every M minutes of watch time:

ads: {
  frequency: {
    mode: 'time',
    intervalMinutes: 3,      // Ad every 3 minutes
    minSessionMinutes: 1     // No ads in first minute
  }
}

Platform-optimized

Let the platform determine optimal frequency:

ads: {
  frequency: {
    mode: 'platform-optimized'
  }
}

Uses heuristics based on:

Session depth
Content completion rates
Aggregate engagement data

Native ad styling

Ads render as native feed cards matching your theme. Customize the sponsored label:

theme: {
  sponsoredLabel: {
    text: 'Ad',
    textColor: '#FFFFFF',
    backgroundColor: 'rgba(0, 0, 0, 0.7)',
    fontSize: 11,
    position: 'topRight'
  }
}

Styling options

Option	Description
`text`	Label text: “Ad”, “Sponsored”, etc.
`textColor`	Label text color
`backgroundColor`	Label background color
`fontSize`	Text size in points
`position`	Corner: topLeft, topRight, bottomLeft, bottomRight

Ad events

Handle ad-related events in your app:

iOS
React Native

class AdEventHandler: ShortkitDelegate {
    func shortKit(_ shortKit: shortkit, didShowAd ad: Ad) {
        analytics.track("ad_impression", properties: [
            "adId": ad.id,
            "position": ad.position
        ])
    }

    func shortKit(_ shortKit: shortkit, didCompleteAd ad: Ad) {
        analytics.track("ad_completed", properties: [
            "adId": ad.id,
            "watchTime": ad.watchTime
        ])
    }

    func shortKit(_ shortKit: shortkit, adDidFail error: AdError) {
        print("Ad failed: \(error.message)")
    }
}

<ShortkitFeed
  onAdImpression={(ad) => {
    analytics.track('ad_impression', {
      adId: ad.id,
      position: ad.position
    });
  }}
  onAdCompleted={(ad) => {
    analytics.track('ad_completed', {
      adId: ad.id,
      watchTime: ad.watchTime
    });
  }}
  onAdError={(error) => {
    console.error('Ad error:', error);
  }}
/>

Available events

Event	Description
`adImpression`	Ad rendered in feed
`adStarted`	Ad playback began
`adFirstQuartile`	25% of ad watched
`adMidpoint`	50% of ad watched
`adThirdQuartile`	75% of ad watched
`adCompleted`	Ad finished playing
`adSkipped`	User skipped the ad
`adClicked`	User tapped the ad
`adError`	Ad failed to load or play

VAST compliance

The SDK automatically handles VAST tracking requirements:

Impression tracking
Quartile events (25%, 50%, 75%)
Completion tracking
Click tracking
Error reporting

This ensures accurate reporting in Google Ad Manager and proper billing.

Testing ads

Test mode

Enable test ads during development:

shortkit.initialize({
  apiKey: 'pk_live_...',
  config: {
    ads: {
      enabled: true,
      testMode: true  // Shows test ads
    }
  }
});

Test mode:

Shows Google test ad creatives
No real impressions recorded
No revenue generated

Ad Inspector

Debug ad delivery:

Enable debug logging
View ad request/response in console
Check fill status and errors

shortkit.setLogLevel('verbose');

Best practices

Start with conservative frequency

Begin with 1 ad every 6-8 videos. Monitor retention metrics before increasing.

Monitor user experience

Track session length and return rates. If they drop after changing ad frequency, roll back.

Use A/B testing

Test different frequencies to find the optimal balance between revenue and engagement.

Style ads to match your feed

Native-looking ads perform better and annoy users less than disruptive formats.

Exclude sensitive content

Map content categories carefully to avoid inappropriate ad/content combinations.

Platform

Integration

Overview

Account setup

Option 1: Self-managed

Option 2: Platform-managed

SDK configuration

Ad frequency modes

Count-based

Time-based

Platform-optimized

Native ad styling

Styling options

Ad events

Available events

VAST compliance

Testing ads

Test mode

Ad Inspector

Best practices

Next steps

Ad management

A/B testing

Platform

Integration

​Overview

​Account setup

​Option 1: Self-managed

​Option 2: Platform-managed

​SDK configuration

​Ad frequency modes

​Count-based

​Time-based

​Platform-optimized

​Native ad styling

​Styling options

​Ad events

​Available events

​VAST compliance

​Testing ads

​Test mode

​Ad Inspector

​Best practices

​Next steps

Ad management

A/B testing

Overview

Account setup

Option 1: Self-managed

Option 2: Platform-managed

SDK configuration

Ad frequency modes

Count-based

Time-based

Platform-optimized

Native ad styling

Styling options

Ad events

Available events

VAST compliance

Testing ads

Test mode

Ad Inspector

Best practices

Next steps