Skip to content
KasskeepKasskeep Docs

Ad unit mapping

Each app maps your ad unit names (for example revive or daily_chest) to network ad unit ids. The SDK and events use your names; callbacks are matched by network id.

  • A name is 1 to 100 letters, digits or . _ : -.
  • One name can hold several ids per network (up to 20), typically one for iOS and one for Android. Each id can carry a platform label ios or android. The label is for display and audit only; matching ignores it.
Terminal window
npx @kasskeep/cli ads unit-set --id app_xxx --name revive --admob ios:ca-app-pub-123/456 --admob android:ca-app-pub-123/789
npx @kasskeep/cli ads unit-set --id app_xxx --name revive --levelplay ios:kq2tbm5g3n7r9wxy,android:p8w3n5v2k7r9q4xz
npx @kasskeep/cli ads units --id app_xxx
npx @kasskeep/cli ads unit-remove --id app_xxx --name revive

The ids you pass replace that network’s ids under the name; an empty value removes the network. With the admin API:

PUT /v1/admin/tenants/:tenant_id/apps/:app_id/ad-units/revive
{"networks": {"levelplay": [{"id": "<iOS id>", "platform": "ios"}, {"id": "<Android id>", "platform": "android"}], "admob": ["ca-app-pub-xxx/111"]}}

A network value can be one id string, an array of ids or {id, platform} objects, or null to remove it. Networks not in the body are left unchanged.

One id, one name

Section titled “One id, one name”

A production id can belong to only one name in an app and network; a second name gets 409 ad_unit_id_in_use. Two exceptions:

  • The networks’ official test ad units (AdMob demo units and the LevelPlay sample app units), which every app shares.
  • Apps with ads_allow_shared_test_units turned on (npx @kasskeep/cli apps update --id app_dev --ads-allow-shared-test-units true). Use it only for development apps.

When one id maps to several names, Kasskeep uses the name the client sent back: LevelPlay’s custom_ad_unit, or ad_unit=<name> inside AdMob’s and MAX’s custom_data (for example ad_unit=revive&stage=3). If that name is missing or not a candidate, the callback is treated as unmapped.

Unmapped ad units

Section titled “Unmapped ad units”

Each app has ads_unmapped_policy:

  • reject (default): a callback whose ad unit is not mapped creates no event, no webhook and no reward record. It returns 200 {"outcome": "unmapped_ignored"} so the network does not retry, and is counted in the unmatched list.
  • emit: the event is sent with ad_unit: null and your backend must filter it.
Terminal window
npx @kasskeep/cli apps update --id app_xxx --ads-unmapped-policy reject
npx @kasskeep/cli ads unmatched --id app_xxx --limit 50

The unmatched list shows network, ad unit id, count, first and last seen. When a real ad unit shows up there, map it; later callbacks are recorded, earlier ones are not replayed.