@admoai/sdk-scenarios

The scenarios every AdMoai mobile SDK (iOS, Android, Flutter) must pass against a real decision-engine: given a request, the outcome a publisher's app observes. One definition, executed by a thin interpreter in each SDK, so the three cannot make different claims.

This package is data only: scenarios.json (the manifest, schemaVersion inside) and scenarios.feature, the same scenarios rendered as Gherkin for a PM or an integrating publisher to read. The JSON is what the SDK runners execute; the feature is generated from it. Neither carries URLs, hosts, credentials or tenant identifiers — check.sh refuses a release whose manifest does.

For an SDK

Vendor one version and pin it; your CI verifies the vendored bytes against the published tarball, and your tests read the vendored file (they never touch the network):

curl -sSfL "https://registry.npmjs.org/@admoai/sdk-scenarios/-/sdk-scenarios-$VERSION.tgz" \
  | tar -xzO package/scenarios.json | cmp - path/to/vendored/scenarios.json

From schemaVersion 2 the manifest also holds fixtureScenarios: offline scenarios that decode a golden decision-wire file, so vendor fixtures/golden-wire/ (the whole directory) beside the manifest and verify those bytes the same way, file by file, against the tarball's package/fixtures/golden-wire/<file>. A runner that cannot execute fixtureScenarios must refuse a schemaVersion 2 manifest.

For adhub (the source)

The source of truth is sdk/scenarios/ in admoai/adhub. To change a scenario: edit scenarios.json, regenerate the Gherkin with go run ./tools/sdkfeaturegen from the repository root, bump version in package.json (minor: added or tightened; major: removed or a key renamed), add a CHANGELOG.md entry, and run sdk/scenarios/check.sh. Merging to main publishes the new version (.github/workflows/sdk-scenarios-release.yml, which first runs sdk/scenarios/stage-fixtures.sh to copy adhub's ui/platform/lib/ad-formats/golden-wire/*.json into the package's fixtures/golden-wire/; that directory is never committed, and a change to a golden file needs a version bump too); each SDK then moves to it in its own PR. See docs/guides/sdk-ci.md.

Schema versions

A runner must refuse a schemaVersion it does not execute.

| schemaVersion | Adds | Package | | --- | --- | --- | | 1 | live scenarios | 1.0.0 | | 2 | fixtureScenarios (offline, golden wire) | 1.2.0 | | 3 | slideTracking on a fixture scenario | 1.3.0 | | 4 | live expect.creative keys metadata, templateKey, contentKeys, styleIn, journeyStageKey (ST1-ST12) | 1.4.0 | | 5 | live expect.creative keys slides, clickKeys, and slideTracking on a live scenario (ST13-ST21, Carousel ads and Journey screens) | 1.5.0 (ST20-ST21 in 1.6.0) |

The v4 keys, same semantics as the fixture keys of the same name: metadata is limited to effectiveStandardFormatKey, effectiveStandardFormatVersion, templateSource and assetContext (exact value per key, null = absent); templateKey is the served template.key; contentKeys is the exact set of plain content keys (order not asserted); styleIn is a non-empty list the served template.style belongs to; journeyStageKey is the served journey.stageKey (only with "journey": true). Live runs of ST1-ST12 need the sdk_st_* placements of adhub's mock seed.

The v5 keys, same semantics as the fixture keys of the same name: slides is the ordered, exact list of the served creative's slides (slideId, position 1..N, and the exact sets contentKeys, viewKeys, clickKeys); clickKeys is the exact set of creative-level click tracker keys (a Carousel has none). A live slideTracking takes the steps slideView: n, slideClick: n and fireClick: null (n is a 1-based slide position) and expects the exact ordered beacons plus engineAcceptsEveryBeacon: true (as in pinTracking); thirdPartyBeacons is not allowed, and it requires expect.outcome: "served" and expect.creative.slides. Live runs of ST13-ST19 need the sdk_st_carousel_* placements of adhub's mock seed, and ST20-ST21 (a Journey screen on the Carousel standard, package 1.6.0) the sdk_st_journey_carousel one.

L9 (package 1.7.0) needs the sdk_locale_default_only placement of the mock seed: its Ad has the locales de (default) and en, and its creative holds values in de only. It relies on the live runners requesting en (their shared Accept-Language): a runner that asked for de would not exercise the fallback.