@admoai/sdk-scenarios 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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

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.3.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: 3
+# Manifest schemaVersion: 4
 
 Feature: Cross-SDK decision & tracking contract
   Shared cross-SDK E2E scenario manifest. ONE definition, executed by a thin interpreter in each
@@ -385,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

package/scenarios.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 3,
+  "schemaVersion": 4,
   "description": "Shared cross-SDK E2E scenario manifest. ONE definition, executed by a thin interpreter in each SDK, so the three suites cannot drift. Declarative only: given a request, expect an outcome. Sponsored Pin tracking scenarios add `pinTracking`: the point-tracking calls an app makes on the served pins, as data, and the beacons that must reach the engine. Procedural scenarios (log capture, concurrency, retry, TTL waits) stay hand-written per SDK. Mirrored byte-identically into all three repos; a checksum test fails the build if the copies diverge. Every expected value here was verified against a live local decision-engine before being written. `fixtureScenarios` (schemaVersion 2) run offline: each decodes one golden decision-wire file (ui/platform/lib/ad-formats/golden-wire in adhub, shipped in this package under fixtures/golden-wire/) after optional `edits`, and asserts what the publisher's app 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. 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.",
   "scenarios": [
     {
@@ -941,6 +941,350 @@
           "engineAcceptsEveryBeacon": true
         }
       }
+    },
+    {
+      "id": "ST1",
+      "title": "a Card with only its required content serves under the Card standard",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_card_min"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": false,
+          "templateKey": "card",
+          "contentKeys": [
+            "image",
+            "destination_url"
+          ],
+          "metadata": {
+            "effectiveStandardFormatKey": "card",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": null
+          }
+        }
+      }
+    },
+    {
+      "id": "ST2",
+      "title": "a Card with every optional content serves them all, in a style the standard defines",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_card_full"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": false,
+          "templateKey": "card",
+          "contentKeys": [
+            "image",
+            "brand_logo",
+            "headline",
+            "supporting_text",
+            "cta_text",
+            "destination_url"
+          ],
+          "metadata": {
+            "effectiveStandardFormatKey": "card",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": null
+          },
+          "styleIn": [
+            "default",
+            "tall"
+          ]
+        }
+      }
+    },
+    {
+      "id": "ST3",
+      "title": "an Expandable Banner with only its required content serves under the Expandable Banner standard",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_expandable_banner_min"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": false,
+          "templateKey": "expandable_banner",
+          "contentKeys": [
+            "teaser_image",
+            "expanded_image",
+            "destination_url"
+          ],
+          "metadata": {
+            "effectiveStandardFormatKey": "expandable_banner",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": null
+          }
+        }
+      }
+    },
+    {
+      "id": "ST4",
+      "title": "an Expandable Banner with every optional content serves them all",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_expandable_banner_full"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": false,
+          "templateKey": "expandable_banner",
+          "contentKeys": [
+            "teaser_image",
+            "teaser_headline",
+            "expanded_image",
+            "headline",
+            "supporting_text",
+            "cta_text",
+            "destination_url",
+            "disclaimer"
+          ],
+          "metadata": {
+            "effectiveStandardFormatKey": "expandable_banner",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": null
+          }
+        }
+      }
+    },
+    {
+      "id": "ST5",
+      "title": "a Branded Asset with only its required content serves with its asset context",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_branded_assets_min"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": false,
+          "templateKey": "branded_assets",
+          "contentKeys": [
+            "branded_image"
+          ],
+          "metadata": {
+            "effectiveStandardFormatKey": "branded_assets",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": "vehicle_marker"
+          }
+        }
+      }
+    },
+    {
+      "id": "ST6",
+      "title": "a Branded Asset with every optional content serves them all, with its asset context",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_branded_assets_full"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": false,
+          "templateKey": "branded_assets",
+          "contentKeys": [
+            "branded_image",
+            "accessible_label",
+            "destination_url"
+          ],
+          "metadata": {
+            "effectiveStandardFormatKey": "branded_assets",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": "vehicle_marker"
+          }
+        }
+      }
+    },
+    {
+      "id": "ST7",
+      "title": "a Standard Video with only its required content serves under the Standard Video standard",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_standard_video_min"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": false,
+          "templateKey": "standard_video",
+          "contentKeys": [
+            "video_asset",
+            "poster_image"
+          ],
+          "metadata": {
+            "effectiveStandardFormatKey": "standard_video",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": null
+          }
+        }
+      }
+    },
+    {
+      "id": "ST8",
+      "title": "a Standard Video with every optional content serves them all",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_standard_video_full"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": false,
+          "templateKey": "standard_video",
+          "contentKeys": [
+            "video_asset",
+            "poster_image",
+            "brand_logo",
+            "headline",
+            "supporting_text",
+            "cta_text",
+            "destination_url",
+            "disclaimer"
+          ],
+          "metadata": {
+            "effectiveStandardFormatKey": "standard_video",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": null
+          }
+        }
+      }
+    },
+    {
+      "id": "ST9",
+      "title": "a standard Ad whose creative cannot satisfy its standard's contract is not served",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_card_incomplete"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "noAd"
+      }
+    },
+    {
+      "id": "ST10",
+      "title": "a legacy creative names no standard and carries no asset context",
+      "request": {
+        "placements": [
+          {
+            "key": "home"
+          }
+        ]
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": false,
+          "metadata": {
+            "effectiveStandardFormatKey": null,
+            "effectiveStandardFormatVersion": null,
+            "templateSource": null,
+            "assetContext": null
+          }
+        }
+      }
+    },
+    {
+      "id": "ST11",
+      "title": "a Journey screen that cannot satisfy its standard is skipped and the next stage's screen answers",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_journey_skip"
+          }
+        ],
+        "session": "auto",
+        "journeyOpt": "in"
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": true,
+          "journeyStageKey": "complete",
+          "templateKey": "card",
+          "metadata": {
+            "effectiveStandardFormatKey": "card",
+            "effectiveStandardFormatVersion": 1,
+            "templateSource": "admoai_standard",
+            "assetContext": null
+          }
+        }
+      }
+    },
+    {
+      "id": "ST12",
+      "title": "a Journey screen serves the Card style saved on it",
+      "request": {
+        "placements": [
+          {
+            "key": "sdk_st_journey_styles"
+          }
+        ],
+        "session": "auto",
+        "journeyOpt": "in"
+      },
+      "expect": {
+        "outcome": "served",
+        "decisions": 1,
+        "creative": {
+          "journey": true,
+          "templateKey": "card",
+          "styleIn": [
+            "default",
+            "tall"
+          ]
+        }
+      }
     }
   ],
   "fixtureScenarios": [