@admoai/sdk-scenarios 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ Versioning: a scenario added or an `expect` tightened is a **minor** release; a
 removed, or a `request`/`expect` key renamed (every SDK's interpreter must change), is a
 **major** one. Each SDK vendors one version and its own CI checks the vendored bytes against it.
 
+## 1.4.0 — 2026-11-08
+
+Adds live scenarios ST1-ST12 for the standard native formats (admoai/adhub#4733): what the
+engine now serves, asserted against a real decision-engine, and moves `schemaVersion` to 4.
+Five new live `expect.creative` keys, each with exactly the semantics of the fixture key of the
+same name, so an interpreter can share one check between `fixtureScenarios` and `scenarios`:
+- `metadata`: an object limited to `effectiveStandardFormatKey`, `effectiveStandardFormatVersion`,
+  `templateSource` and `assetContext`. Each listed key must equal the served value exactly; `null`
+  means the key is absent from the served metadata.
+- `templateKey`: the served `template.key`.
+- `contentKeys`: the served creative's plain content keys are exactly this set (order is not
+  asserted; slides and matched points are not plain contents).
+- `styleIn`: a non-empty list; the served `template.style` is one of them.
+- `journeyStageKey`: the served creative's `journey.stageKey` equals it; only valid with
+  `"journey": true`.
+ST1-ST8 serve the min and full Ad of Card, Expandable Banner, Branded Assets and Standard Video;
+ST9 is a Card whose creative cannot satisfy its contract and is not served (no ad); ST10 is the
+legacy `home` placement, whose metadata names no standard and carries no asset context; ST11 is a
+Journey whose first stage's screen cannot satisfy its standard, skipped, so the next stage's screen
+answers; ST12 is a Journey screen serving the saved Card style. Carousel is not in this version:
+its slides are not served yet. Live runs need the `sdk_st_*` placements of the mock seed (11: nine
+Ad placements and the two Journey entry placements `sdk_st_journey_skip` and
+`sdk_st_journey_styles`). A runner that does not know `schemaVersion` 4 must refuse the manifest;
+adopting 1.4.0 requires executing the five keys. The 39 live scenarios and F1-F25 are unchanged.
+
+## 1.3.0 — 2026-11-05
+
+Adds fixture scenarios F16–F25 with a `slideTracking` block (admoai/adhub#4733): what the app
+dispatches when it reports slides and interactions on a decoded standard creative, offline.
+A slide view goes out once per served response, keyed on its signed URL, and again for a new
+response (F16, F17). A slide click before its view sends the view, then the click, then the
+creative's applicable third-party click trackers once per click. A slide view never sends them
+(F18-F20). A Carousel has no creative click (F21). `fireClick` with no key sends `default`
+(F22). Expand, close and asset tap are verbatim custom events, not clicks (F23, F24). A
+Standard Video without a destination sends no click (F25). New edit level `tracking` (the
+creative's tracking object), used to inject third-party trackers on `.example` hosts. A
+`schemaVersion` moves to 3, so a runner that knows only 2 refuses the manifest instead of
+skipping `slideTracking` silently; adopting 1.3.0 requires executing it.
+
 ## 1.2.0 — 2026-11-05
 
 Adds `fixtureScenarios` F1–F15 and moves `schemaVersion` to 2 (admoai/adhub#4733): offline

package/README.md

@@ -37,3 +37,21 @@ or a key renamed), add a `CHANGELOG.md` entry, and run `sdk/scenarios/check.sh`.
 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 |
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@admoai/sdk-scenarios",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "The cross-SDK decision & tracking scenarios every AdMoai SDK asserts against a real decision-engine. Data only.",
   "license": "MIT",
   "files": [

package/scenarios.feature

@@ -6,7 +6,7 @@
 # promises a publisher's app, in the same words for all three. CI regenerates it and fails on
 # any difference, so it cannot drift from what the runners execute.
 # How it is published and kept fresh: docs/guides/sdk-ci.md, Section 7.
-# Manifest schemaVersion: 2
+# Manifest schemaVersion: 4
 
 Feature: Cross-SDK decision & tracking contract
   Shared cross-SDK E2E scenario manifest. ONE definition, executed by a thin interpreter in each
@@ -22,7 +22,15 @@ Feature: Cross-SDK decision & tracking contract
   reads from the decoded creative. `contentKeys` is the exact set of plain content keys (slides
   and matched points are asserted through their own fields); a key in `contentKeysAbsent` must
   decode as absent (null), never as an empty string or a placeholder; a null in `metadata` means
-  absent. A runner that does not execute fixtureScenarios must refuse schemaVersion 2.
+  absent. A runner that does not execute fixtureScenarios must refuse schemaVersion 2. A fixture
+  scenario may add `slideTracking` (package 1.3.0, schemaVersion 3; a runner that does not
+  execute it must refuse schemaVersion 3): `steps` the app takes on the decoded creative
+  (`slideView`/`slideClick` with a 1-based slide index, `newResponse`, `fireClick` with a key or
+  null for no key, `custom` with a key) and the beacons that must be dispatched: `beacons` is
+  the exact ordered list of first-party beacons, each named by the tracker it must be
+  (`slide`+`view`/`click`, or creative `click`/`custom`, with `response`), and
+  `thirdPartyBeacons` the exact multiset of third-party tracker ids dispatched (their order is
+  not asserted). An edit `at` `tracking` targets the creative's tracking object.
 
   @L @native
   Scenario: L1 — a normal native ad serves with complete, well-formed metadata
@@ -377,6 +385,153 @@ Feature: Cross-SDK decision & tracking contract
     And every tap and every click sends its beacon, on every call
     And the engine accepts every beacon
 
+  @ST @standard-formats
+  Scenario: ST1 — a Card with only its required content serves under the Card standard
+    Given the app requests placement "sdk_st_card_min"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is not a Journey Ad
+    And the creative's assetContext is absent
+    And the creative's effectiveStandardFormatKey is "card"
+    And the creative's effectiveStandardFormatVersion is 1
+    And the creative's templateSource is "admoai_standard"
+    And the template key is "card"
+    And the creative's contents are exactly "image", "destination_url"
+
+  @ST @standard-formats
+  Scenario: ST2 — a Card with every optional content serves them all, in a style the standard defines
+    Given the app requests placement "sdk_st_card_full"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is not a Journey Ad
+    And the creative's assetContext is absent
+    And the creative's effectiveStandardFormatKey is "card"
+    And the creative's effectiveStandardFormatVersion is 1
+    And the creative's templateSource is "admoai_standard"
+    And the template key is "card"
+    And the creative's contents are exactly "image", "brand_logo", "headline", "supporting_text", "cta_text", "destination_url"
+    And the template style is one of "default", "tall"
+
+  @ST @standard-formats
+  Scenario: ST3 — an Expandable Banner with only its required content serves under the Expandable Banner standard
+    Given the app requests placement "sdk_st_expandable_banner_min"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is not a Journey Ad
+    And the creative's assetContext is absent
+    And the creative's effectiveStandardFormatKey is "expandable_banner"
+    And the creative's effectiveStandardFormatVersion is 1
+    And the creative's templateSource is "admoai_standard"
+    And the template key is "expandable_banner"
+    And the creative's contents are exactly "teaser_image", "expanded_image", "destination_url"
+
+  @ST @standard-formats
+  Scenario: ST4 — an Expandable Banner with every optional content serves them all
+    Given the app requests placement "sdk_st_expandable_banner_full"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is not a Journey Ad
+    And the creative's assetContext is absent
+    And the creative's effectiveStandardFormatKey is "expandable_banner"
+    And the creative's effectiveStandardFormatVersion is 1
+    And the creative's templateSource is "admoai_standard"
+    And the template key is "expandable_banner"
+    And the creative's contents are exactly "teaser_image", "teaser_headline", "expanded_image", "headline", "supporting_text", "cta_text", "destination_url", "disclaimer"
+
+  @ST @standard-formats
+  Scenario: ST5 — a Branded Asset with only its required content serves with its asset context
+    Given the app requests placement "sdk_st_branded_assets_min"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is not a Journey Ad
+    And the creative's assetContext is "vehicle_marker"
+    And the creative's effectiveStandardFormatKey is "branded_assets"
+    And the creative's effectiveStandardFormatVersion is 1
+    And the creative's templateSource is "admoai_standard"
+    And the template key is "branded_assets"
+    And the creative's contents are exactly "branded_image"
+
+  @ST @standard-formats
+  Scenario: ST6 — a Branded Asset with every optional content serves them all, with its asset context
+    Given the app requests placement "sdk_st_branded_assets_full"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is not a Journey Ad
+    And the creative's assetContext is "vehicle_marker"
+    And the creative's effectiveStandardFormatKey is "branded_assets"
+    And the creative's effectiveStandardFormatVersion is 1
+    And the creative's templateSource is "admoai_standard"
+    And the template key is "branded_assets"
+    And the creative's contents are exactly "branded_image", "accessible_label", "destination_url"
+
+  @ST @standard-formats
+  Scenario: ST7 — a Standard Video with only its required content serves under the Standard Video standard
+    Given the app requests placement "sdk_st_standard_video_min"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is not a Journey Ad
+    And the creative's assetContext is absent
+    And the creative's effectiveStandardFormatKey is "standard_video"
+    And the creative's effectiveStandardFormatVersion is 1
+    And the creative's templateSource is "admoai_standard"
+    And the template key is "standard_video"
+    And the creative's contents are exactly "video_asset", "poster_image"
+
+  @ST @standard-formats
+  Scenario: ST8 — a Standard Video with every optional content serves them all
+    Given the app requests placement "sdk_st_standard_video_full"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is not a Journey Ad
+    And the creative's assetContext is absent
+    And the creative's effectiveStandardFormatKey is "standard_video"
+    And the creative's effectiveStandardFormatVersion is 1
+    And the creative's templateSource is "admoai_standard"
+    And the template key is "standard_video"
+    And the creative's contents are exactly "video_asset", "poster_image", "brand_logo", "headline", "supporting_text", "cta_text", "destination_url", "disclaimer"
+
+  @ST @standard-formats
+  Scenario: ST9 — a standard Ad whose creative cannot satisfy its standard's contract is not served
+    Given the app requests placement "sdk_st_card_incomplete"
+    Then no ad is served, and the placement answers with a clean no-fill
+
+  @ST @standard-formats
+  Scenario: ST10 — a legacy creative names no standard and carries no asset context
+    Given the app requests placement "home"
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is not a Journey Ad
+    And the creative's assetContext is absent
+    And the creative's effectiveStandardFormatKey is absent
+    And the creative's effectiveStandardFormatVersion is absent
+    And the creative's templateSource is absent
+
+  @ST @standard-formats
+  Scenario: ST11 — a Journey screen that cannot satisfy its standard is skipped and the next stage's screen answers
+    Given the app requests placement "sdk_st_journey_skip"
+    And the request carries a fresh session id
+    And the user has opted in to Journey Ads
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is a Journey Ad
+    And the creative's assetContext is absent
+    And the creative's effectiveStandardFormatKey is "card"
+    And the creative's effectiveStandardFormatVersion is 1
+    And the creative's templateSource is "admoai_standard"
+    And the template key is "card"
+    And the Journey stage is "complete"
+
+  @ST @standard-formats
+  Scenario: ST12 — a Journey screen serves the Card style saved on it
+    Given the app requests placement "sdk_st_journey_styles"
+    And the request carries a fresh session id
+    And the user has opted in to Journey Ads
+    Then an ad is served
+    And exactly 1 decision is returned
+    And the creative is a Journey Ad
+    And the template key is "card"
+    And the template style is one of "default", "tall"
+
   @F @fixture
   Scenario: F1 — a Native Display creative exposes its standard format, version and template source
     Given the app decodes the golden card.full response
@@ -595,3 +750,141 @@ Feature: Cross-SDK decision & tracking contract
     And slide 1 is "slide_01JDY02N8MA2K2HKQ74989YS99" with contents "image", "headline", "supporting_text", "cta_text", "destination_url", view trackers "slide_view" and click trackers "default"
     And slide 2 is "slide_01JD04H8GY801VF8Y0FHETP6XA" with contents "image", "headline", "supporting_text", "cta_text", "destination_url", view trackers "slide_view" and click trackers "default"
     And slide 3 is "slide_01JDRGMFSTZXQ7ES1QBCF0DR2X" with contents "image", "headline", "supporting_text", "cta_text", "destination_url", view trackers "slide_view" and click trackers "default"
+
+  @F @fixture
+  Scenario: F16 — a slide's view beacon is sent once per served response, however often the slide is shown
+    Keyed on the signed view URL, never on the slideId: re-rendering or scrolling back to a
+    slide must not count it again (BR-SDK-04, Q19).
+
+    Given the app decodes the golden carousel.full response
+    And with third-party trackers "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_other", "tpt_fixture_impression"
+    When the app reports slide 1 as viewed
+    And the app reports slide 1 as viewed
+    And the app reports slide 2 as viewed
+    And the app reports slide 1 as viewed
+    Then the response decodes
+    And exactly these beacons are sent, in this order:
+    And slide 1's "slide_view" view beacon
+    And slide 2's "slide_view" view beacon
+    And no third-party tracker is sent
+
+  @F @fixture
+  Scenario: F17 — the same slide in a new decision response counts again
+    A new response carries new signed URLs for the same slides. The runner simulates it by
+    decoding the same golden file again with every first-party tracker URL suffixed
+    `&response=N` (N = 2, 3, ...); `response` in an expected beacon names which one (default 1).
+
+    Given the app decodes the golden carousel.full response
+    And with third-party trackers "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_other", "tpt_fixture_impression"
+    When the app reports slide 1 as viewed
+    And the app decodes a new decision response for the same ad
+    And the app reports slide 1 as viewed
+    And the app reports slide 1 as viewed
+    Then the response decodes
+    And exactly these beacons are sent, in this order:
+    And slide 1's "slide_view" view beacon
+    And slide 1's "slide_view" view beacon from response 2
+    And no third-party tracker is sent
+
+  @F @fixture
+  Scenario: F18 — a slide clicked before its view was sent sends the view, then the click, then the creative's applicable third-party click trackers once
+    Applicable means a click tracker matching any click, or the `default` click specifically; a
+    tracker for another click key and an impression tracker do not fire (BR-SDK-05, Q14, Q18).
+
+    Given the app decodes the golden carousel.full response
+    And with third-party trackers "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_other", "tpt_fixture_impression"
+    When the user clicks slide 2
+    Then the response decodes
+    And exactly these beacons are sent, in this order:
+    And slide 2's "slide_view" view beacon
+    And slide 2's "default" click beacon
+    And the third-party trackers sent are exactly "tpt_fixture_click_any", "tpt_fixture_click_default"
+
+  @F @fixture
+  Scenario: F19 — a slide clicked after its view sends only the click, on every click
+    Given the app decodes the golden carousel.full response
+    And with third-party trackers "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_other", "tpt_fixture_impression"
+    When the app reports slide 2 as viewed
+    And the user clicks slide 2
+    And the user clicks slide 2
+    Then the response decodes
+    And exactly these beacons are sent, in this order:
+    And slide 2's "slide_view" view beacon
+    And slide 2's "default" click beacon
+    And slide 2's "default" click beacon
+    And the third-party trackers sent are exactly "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_any", "tpt_fixture_click_default"
+
+  @F @fixture
+  Scenario: F20 — slide views never send third-party click trackers
+    Given the app decodes the golden carousel.full response
+    And with third-party trackers "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_other", "tpt_fixture_impression"
+    When the app reports slide 1 as viewed
+    And the app reports slide 2 as viewed
+    And the app reports slide 3 as viewed
+    Then the response decodes
+    And exactly these beacons are sent, in this order:
+    And slide 1's "slide_view" view beacon
+    And slide 2's "slide_view" view beacon
+    And slide 3's "slide_view" view beacon
+    And no third-party tracker is sent
+
+  @F @fixture
+  Scenario: F21 — a Carousel has no creative-level click: fireClick sends nothing, so slide clicks go through the slide helper
+    Publishers must not route a slide tap through fireClick (BR-SDK-03, Q9).
+
+    Given the app decodes the golden carousel.full response
+    And with third-party trackers "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_other", "tpt_fixture_impression"
+    When the app calls fireClick with no key
+    Then the response decodes
+    And no first-party beacon is sent
+    And no third-party tracker is sent
+
+  @F @fixture
+  Scenario: F22 — fireClick with no key sends the default click of a standard
+    Every standard seeds its click with key `default`, which is what fireClick sends without a
+    key (BR-SDK-06, Q12).
+
+    Given the app decodes the golden card.full response
+    And with third-party trackers "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_other", "tpt_fixture_impression"
+    When the app calls fireClick with no key
+    Then the response decodes
+    And exactly these beacons are sent, in this order:
+    And the creative's "default" click beacon
+    And the third-party trackers sent are exactly "tpt_fixture_click_any", "tpt_fixture_click_default"
+
+  @F @fixture
+  Scenario: F23 — expand and close are sent verbatim as custom events and are not clicks
+    The publisher calls them when the banner actually expands or closes; no click is sent and no
+    third-party click tracker fires (BR-SDK-07).
+
+    Given the app decodes the golden expandable_banner.full response
+    And with third-party trackers "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_other", "tpt_fixture_impression"
+    When the app sends the custom event "expand"
+    And the app sends the custom event "close"
+    Then the response decodes
+    And exactly these beacons are sent, in this order:
+    And the creative's "expand" custom beacon
+    And the creative's "close" custom beacon
+    And no third-party tracker is sent
+
+  @F @fixture
+  Scenario: F24 — an asset tap is sent verbatim as a custom event and is not a click
+    BR-SDK-07.
+
+    Given the app decodes the golden branded_assets.full response
+    And with third-party trackers "tpt_fixture_click_any", "tpt_fixture_click_default", "tpt_fixture_click_other", "tpt_fixture_impression"
+    When the app sends the custom event "asset_tap"
+    Then the response decodes
+    And exactly these beacons are sent, in this order:
+    And the creative's "asset_tap" custom beacon
+    And no third-party tracker is sent
+
+  @F @fixture
+  Scenario: F25 — a Standard Video without a destination sends no click
+    No destination means no click action and no click tracker (BR-SDK-08).
+
+    Given the app decodes the golden standard_video.minimal response
+    When the app calls fireClick with no key
+    Then the response decodes
+    And no first-party beacon is sent
+    And no third-party tracker is sent