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 the placement parameter is required in all moments sdk and api requests for a full list of payload parameters, see passing payload values docid\ yz38zu4 miummwtnnsg98 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 https //app momentscience com/account/tools/placements the page https //app momentscience com/account/tools/placements 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 docid\ vuwxafh3vyoaijb5idtfd single vs multiple rules one rule assigned that rule is applied in full multiple rules assigned the rules are combined, only offers that satisfy all assigned rules are eligible the resulting offer set reflects the intersection of all rules on the placement open the select sequence rule(s) dropdown on the placement row to add or remove rules when multiple rules are selected, each rule is honored based on its own settings, contact your account manager if you need help configuring individual rule behavior 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 help\@momentscience com mailto\ help\@momentscience com