Overview
An Engagement Plan is a versioned YAML authoring document that describes ownership, reusable decisions, and purchase choices. Products and channel adapters consume the same plan to produce the experience appropriate to their channel.
Getting Started
- Identify the Plan and Owner
Assign a stable engagementPlanId, declare schemaVersion: "1.1", and select the authorized owning company. Begin with authoringStatus: "draft".
- Define Defaults and Decisions
Create named entries in decisions, each with a default result and ordered decisionRules. Confirm the audience bindings and field types used by conditions.
- Define Purchase Options
Give each choice a unique local ID, a label, enablement, a decisionRef, and its Web or Call settings. Keep routing values in the referenced decision.
- Add Product Configuration
Follow the consuming product's requirements. Page generation requires the appropriate page configuration, template version, approved copy, and assets. See Intelligent TV page configuration for that product's template.
- Validate and Review
Validate the YAML profile, exact schema version, local references, and rule semantics. Verify resource authorization, assets, adapter support, and approval separately before release.
Audience Decisions and Defaults
The following shared decision rules apply to every consuming product.
Decision Structure
decisions is a map of local decision names. Each entry requires a nonempty default result and a decisionRules list. Use an empty list for a default-only decision. Every rule requires a unique ID within that decision, a when condition, and a nonempty override result.
| Result field | Meaning |
|---|
destinationType | Resource ID or exact symbolic type such as Web or Call. Not nullable. |
destinationProvider | Nonblank label for the receiving organization or service. |
destinationAddress | HTTPS or telephone route; null clears the route and must not become a clickable link. |
productObservationRef | Local product observation reference; null clears the reference. |
outcome | Nonblank symbolic result translated by a channel binding, not a committed commercial offer. |
Ordered Evaluation
Each option's decisionRef selects a decision in the same plan.
Rules are evaluated in document order; the first matching rule wins.
Its override replaces only the supplied top-level properties of default.
Unspecified properties retain their defaults; explicit null clears only a field that the result schema permits to be null.
If no rule matches, use the default. An unknown input may allow a later independent rule to match. Overrides are shallow and do not accumulate across matching rules; enabled: false suppresses a purchase option regardless of its decision result.
In the example, a validated purchaseAudience result with code "H"
selects the alternate retailer URL. Other codes or unavailable results retain the default.
The logical key requires a verified binding to the selected audience result; declaring it in YAML does not create a model.
See IH Scores for the existing score codes.
| Condition field | Supported comparisons |
|---|
vectorCode | Exact, case-sensitive eq or nonempty in list. |
vectorOrdinal | Integer eq or in, through a validated ordinal adapter. Do not assume a legacy nominal index is an ordinal or an ordering of propensity. |
vectorValue | Finite numeric eq, or lower/upper bounds using gt, gte, lt, and lte. Do not mix equality with bounds. |
Conditions can compose with all, any, or a single-object not.
Missing, invalid, or ambiguous inputs evaluate as unknown. Only true matches a rule;
negating an unknown input does not turn it into a match.
Risk Prerequisites
Future decisions that combine independent propensity and risk results must explicitly require low risk before selecting a propensity-based treatment. A missing or non-low-risk result must not satisfy that prerequisite; merely placing a high-risk rule first is insufficient. This is an authoring requirement, not a claim that independent multi-model execution is implemented.
An Engagement Plan is generator input, not the JavaScript Page Plan passed directly to the SDK.
The template and channel adapter translate supported decisions into default HTML and
Page Plan configuration.
Unsupported conditions must fail validation rather than silently lose their meaning.
Decision Rule YAML Examples
Each block defines named entries under decisions; merge the entries into your plan's existing decisions map rather than adding duplicate YAML keys. A purchase option selects a decision by its exact decisionRef. The snippets are not standalone Engagement Plans.
Default-Only Decision
decisions:
standard-route:
default:
destinationType: "Web"
destinationProvider: "example-brand"
destinationAddress: "https://brand.example.com/product"
decisionRules: []
An empty rule list always returns the default. With conditional rules, the default also applies when none evaluates to true. Unknown inputs do not create a match, and the consumer must preserve its configured default when a required binding is unavailable or its evaluation deadline is reached.
Multiple Rules: First Match Wins
decisions:
audience-route:
default:
destinationType: "Web"
destinationProvider: "example-brand"
destinationAddress: "https://brand.example.com/product"
decisionRules:
- id: "high"
when:
vectorKey: "purchaseAudience"
field: "vectorCode"
eq: "H"
override:
destinationAddress: "https://brand.example.com/high"
- id: "high-or-medium"
when:
vectorKey: "purchaseAudience"
field: "vectorCode"
in: ["H", "M"]
override:
destinationAddress: "https://brand.example.com/standard-offer"
The rules deliberately overlap for "H" to show why order matters. Review such overlaps explicitly. The first true rule supplies the only override; later matches do not accumulate changes. Here, every selected route inherits destinationType and destinationProvider from the default.
| Audience code | Selected result |
|---|
H | Both rules match; the first selects https://brand.example.com/high. |
M | The second rule selects https://brand.example.com/standard-offer. |
L, N, R, or U | Neither rule matches; use the default product URL. |
| Missing or invalid audience result | Both conditions are unknown; use the default product URL. A valid code U is distinct from an unavailable result, even though both use the default in this example. |
All: Require Every Condition
decisions:
low-risk-high-propensity:
default:
outcome: "standard"
decisionRules:
- id: "qualified"
when:
all:
- vectorKey: "purchaseRisk"
field: "vectorCode"
eq: "LOW"
- vectorKey: "purchasePropensity"
field: "vectorCode"
eq: "H"
override:
outcome: "qualified"
This rule matches only when risk is explicitly "LOW" and propensity is "H". Any false child makes all false. If no child is false but one is unknown, all is unknown. Both cases retain outcome: "standard".
Any: Accept Either Condition
decisions:
audience-review:
default:
outcome: "standard"
decisionRules:
- id: "review-candidate"
when:
any:
- vectorKey: "purchaseAudience"
field: "vectorCode"
in: ["H", "M"]
- vectorKey: "purchaseAudience"
field: "vectorValue"
gte: 2
lt: 3
override:
outcome: "review"
Either a qualifying code or a value in the interval 2 <= value < 3 selects "review". One true child makes any true even if the other is unknown. All-false children produce false; otherwise, an unresolved result is unknown and this decision uses its default. The interval is illustrative and does not establish equivalence between score codes and numeric values.
Not: Negate One Known Condition
decisions:
non-buyer-review:
default:
outcome: "standard"
decisionRules:
- id: "known-code-other-than-n"
when:
not:
vectorKey: "purchaseAudience"
field: "vectorCode"
eq: "N"
override:
outcome: "review"
not takes one condition object, not a list. A valid code other than "N" selects "review"; "N" retains the default. Missing or invalid input remains unknown after negation and also retains the default. This is a negation example, not a low-risk test: a known risk code can be different from "N".
Nested All, Any, and Not
decisions:
gated-presentation:
default:
outcome: "standard"
decisionRules:
- id: "qualified-review"
when:
all:
- vectorKey: "purchaseRisk"
field: "vectorCode"
eq: "LOW"
- any:
- vectorKey: "purchasePropensity"
field: "vectorCode"
in: ["H", "M"]
- vectorKey: "purchasePropensity"
field: "vectorValue"
gte: 2
- not:
vectorKey: "purchasePropensity"
field: "vectorCode"
eq: "N"
override:
outcome: "qualified-review"
The nested rule requires explicit low risk, either qualifying propensity code or value, and a known propensity code other than "N". A numeric match alone cannot overcome an unknown negated code or an unavailable low-risk prerequisite. Only a true result selects the override.
Keys, codes, thresholds, URLs, and outcomes are illustrative. Confirm their bindings and meaning for your integration. The independent risk/propensity examples describe the authoring contract; they do not establish deployed multi-model support. An outcome requires a channel binding to interpret it and does not itself create an offer or route.
Validation and Versioning
- Validate the bounded YAML 1.2 profile before applying the exact declared JSON Schema. Unknown versions and unknown fields must fail validation.
- Check unique decision and option IDs, resolvable local references, condition types, nonempty membership lists, and noncontradictory numeric bounds. Review overlapping rules explicitly.
- Resolve resource references in the authorized Company scope. A value in YAML selects a resource; it does not grant access to it. Quote strings deliberately and do not coerce numeric strings into IDs.
- Pin schema and template versions for reproducible builds. Keep assets with the plan and resolve relative asset paths from the plan directory.
- Use the consuming product's preview and acceptance checks. Structural validity does not verify live bindings, content approval, runtime support, or publication readiness.
Version 1.1 adds optional page configuration and rejects segmentLabels; Vector Lexicons own segment labels. Version 1.0 remains available for historical inputs. Migrate explicitly: legacy names such as companyId, destinationTypeId, model, vectorIndex, and vectorLexiconId are not aliases for the current fields.