Managing Placements
Who is this for: Partners and developers who want to apply different themes and sequence rules to distinct surfaces or pages within a single MomentScience account.
Outcome: Create named placements in the dashboard, map them to integration points using the placement parameter, and control which theme and rules apply to each surface.
Overview
Placements give you a way to organize and control how MomentScience delivers offers across different pages or surfaces in your integration. By passing a placement value in your Moments payload, you can map specific themes and sequence rules to each location, so the checkout page, homepage, and mobile app can each show offers tailored to that context, all from a single account.
When a placement matches a configured entry in your dashboard, MomentScience applies the themes and sequence rules you have assigned to it. When no placement is passed, the placement you have marked as default is used instead.
We recommend passing the placement parameter in every Moments SDK and API request. It is not required: if it is missing, or does not match an active placement, MomentScience uses the placement you marked as default. For a full list of payload parameters, see Passing Payload Values๏ปฟ.
How Placements Works
The placement Parameter
Include placement in every request to identify which page or surface the offer unit is appearing on. The value you pass is matched against your configured placements to determine which themes and sequence rules apply.
// Moments API
{
"api_key": "your-api-key",
"placement": "checkout-confirmation",
"pub_user_id": "user-123"
}Parameter Formatting
MomentScience normalizes placement values to a consistent format on both save and matching:
- All characters are converted to lowercase
- Underscores and spaces are converted to hyphens
- Matching is case-insensitive and ignores formatting differences
This means Home_Page, home_page, home-page, and HOME_PAGE all resolve to the same placement: home-page. You do not need to align the exact formatting between what your integration passes and what is stored in the dashboard, the normalization is applied automatically on both sides.
Input | Stored As |
|---|---|
Homepage_Desktop | homepage-desktop |
Home_Page | home-page |
CHECKOUT CONFIRM | checkout-confirm |
post-transaction | post-transaction |
If your integration passes homepage_desktop and homepagedesktop separately, they normalize to different values (homepage-desktop and homepagedesktop) and are treated as distinct placements.
Managing Placements
Access the Manage Placements page from your dashboard under Tools > Placements.๏ปฟ
The page displays your active placements in a table with columns for placement name, Moment Themes, sequence rules, and last updated date.
Users with Manager or Analyst roles cannot access the Placements section, it is not visible to them in the dashboard.
Adding a Placement Manually
- Click Add Placement on the Manage Placements page.
- Enter a Placement Parameter (required), this is the unique identifier matched against the placement value in your Moments payload (e.g., checkout-confirmation). It is normalized to lowercase and hyphenated on save.
- Enter a Placement Name (optional), a human-readable label for the placement in your dashboard (e.g., "Checkout Confirmation Page").
- Select Moment Themes (optional), one or more themes to serve on this placement.
- Select Sequence Rules (optional), one or more rules to apply to offer sequencing on this placement.
- Click Save.
Editing a Placement
Click the edit control on any active placement row to update its name, Custom Attribute designation, themes, or sequence rules. Save applies all changes for that row at once, toggle state, theme selections, weights, and rule assignments are all saved in a single action.
Archiving and Unarchiving
To deactivate a placement, click Archive on its row. Archived placements no longer influence offer serving, requests matching an archived placement slug fall back to the default placement.
If you need to reactivate an archived placement or reuse its slug, contact your account manager.
Default Placement
One placement is always marked as the default. When a Moments request arrives with no placement value (or null), the default placement's themes and sequence rules are used.
How the default is assigned:
- The first placement you add is automatically set as default.
- When you have two or more placements, a radio button on each row lets you change which one is default. Exactly one placement can be default at a time.
- If you archive the current default, the most recently created remaining placement becomes the new default automatically.
Custom Attribute Placements
Turning on the Custom Attribute toggle on a placement lets it be matched by value against any key in your payload, not just placement. This is useful for segment-based personalization, such as loyalty tier or membership level, without creating a separate placement for every segment.
Matching uses the same normalization as the placement parameter, it's case-insensitive and ignores underscore/hyphen/spacing differences. Internal payload keys (prefixed with _ or internal-) are never checked as candidates.
// "loyalty_tier" here could just as easily be any other key name
{
"api_key": "your-api-key",
"loyalty_tier": "gold-member",
"pub_user_id": "user-123"
}If gold-member is the slug of a placement with Custom Attribute turned on, that placement's theme and sequence rule are applied, even if the request also passes a placement value: the Custom Attribute placement always takes precedence when both match. If the value doesn't match any Custom Attribute placement, the request falls back to standard placement behavior with no error.
Assigning Themes Weight
Each placement can have one or more MomentPerk Themes assigned to it. When multiple themes are assigned, MomentScience distributes serving across them using the weight you configure per theme.
Assigning and Removing Themes
In the placement row, open the Select Moment Theme(s) dropdown. Each theme shows a checkbox to select or deselect it. Selected themes appear at the top of the list with their current weight.
Theme Weights and A/B Distribution
Each theme assigned to a placement has a weight value. Weights determine the relative share of serving traffic each theme receives.
Configuration | Result |
|---|---|
Theme A: weight 1, Theme B: weight 1 | Each theme serves 50% of the time |
Theme A: weight 2, Theme B: weight 1 | Theme A serves ~67%, Theme B ~33% |
Single theme: any weight | That theme serves 100% of requests |
The default weight for any newly assigned theme is 1. Leaving all themes at weight 1 gives each theme equal opportunity.
Theme Priority When theme_id Is Passed in Payload
If your integration passes a theme_id directly in the Moments payload alongside a placement, the explicitly passed theme_id takes priority over the themes configured on the placement. This lets you override the placement's theme assignment on a per-request basis when needed.
If the theme_id passed does not exist or has been archived, MomentScience falls back to the partner's default theme.
Assigning Sequence Rules
Each placement can have one or more sequence rules assigned to it. Sequence rules control which offers are eligible and in what order they appear for that placement.
Sequence Rules must be enabled for your account before you can assign them to placements. Contact your account manager to get started. For full details on how sequence rules work, see Sequence Rules๏ปฟ.
Single vs. Multiple Rules
- One rule assigned: That rule is applied in full.
- Multiple rules assigned: Every Always Apply rule runs, and an offer must pass all of them. If the placement also has weighted rules, one weighted rule is picked per request in proportion to its weight (separately for all-position rules and for each position) and applied on top.
Open the Select Sequence Rule(s) dropdown on the placement row to add or remove rules. Each mapped rule shows two read-only values for this placement: Always Apply and Weight.
Always Apply means the rule runs on every request for this placement. Its weight shows as "-".
A weight means the rule is weighted. Among the weighted rules on this placement, one is picked per request in proportion to its weight. For example, Rule A at 70 and Rule B at 30 run on about 70% and 30% of requests.
Weights are set per placement, so the same rule can carry a different share on different placements. A rule you add starts as Always Apply. Saving the placement never changes the weight of a rule that was already mapped. Only your MomentScience Account Manager can change Always Apply or a weight. Hover a value to see why it is locked.
Placement-Scoped Rules
Sequence rules are scoped to the placement they are assigned to. A rule on one placement does not affect any other placement, and no account-level rule aggregation occurs. This means:
- Requests that match a placement use only that placement's assigned rules.
- If a placement has no rules assigned, offers are returned without sequencing constraints.
- If no placement is passed and a default placement is configured, the default placement's rules apply.
- If no placement is passed and no default placement exists, no sequence rules are applied.
Serving Behavior
When a request arrives, MomentScience resolves the placement, giving precedence to any matching Custom Attribute placement, and applies themes and sequence rules in the following order:
Theme Resolution
- If theme_id is passed in the payload, use that theme (if valid and not archived).
- If the placement has one or more themes assigned, select a theme based on weights.
- If the placement has no themes, or the passed theme_id does not exist, use the partner's default theme.
Sequence Rule Resolution
- If the request includes a placement value that matches an active placement, apply only that placement's sequence rules.
- If no placement is passed but a default placement is configured, apply the default placement's sequence rules.
- If no placement is passed and no default placement exists, serve offers without sequencing constraints.
No Placement Passed
When placement is absent or null in the request:
- If a default placement is configured: its themes and sequence rules are used.
- If no placements exist at all: the default theme is used and offers are served without sequencing constraints.
If you encounter any issues or need support during integration, contact us at [email protected].