Target in-app messages by surface

Public

A surface is the logical page an in-app message is allowed to render on — the bill page, the storefront catalog, the rewards page, and so on. Picking a surface keeps a message exactly where it belongs: a “rate your visit” prompt on the bill, and never on the catalog while a shopper is browsing.

By default a campaign renders on every surface. You only narrow it when you want to — an empty surface selection means “show everywhere”, which is exactly how older campaigns keep working.

Why not just match the URL?

You can still match on a URL pattern, but it’s fragile: customer links carry rotating tokens, and an agency-managed brand can change its domain. The Surface picker is enum-locked — you choose from a fixed list, so there are no typos and no broken matches when a URL changes.

The surfaces

Surface key	Where it shows	Owned by
`bill`	The customer’s bill / receipt page	Active Bill
`storefront_catalog`	The storefront browsing pages (catalog, cart, checkout)	Active Commerce
`storefront_rewards`	The rewards page	Active Loyalty
`storefront_feedback`	The feedback page	Active Feedback
`storefront_reviews`	The reviews page	Active Reviews
`storefront_members`	The membership page	Active Loyalty
`external_website`	A third-party website running the Active Reach SDK	Your team
`external_mobile_screen`	A screen inside your own mobile app	Your team

How a page declares its surface

Active Reach’s own customer pages already declare their surface for you — you don’t need to touch any code for the bill, storefront, rewards, feedback, reviews, or members pages.

On your own website or mobile app, declare the surface with one line where the page or screen loads. It reuses the same SDK call you’d use for page-view analytics:


// URL-bound pages (a route the customer navigates to)
aegis.page('external_website');
 
// SPA-logical screens (a step that doesn't change the URL)
aegis.screen('external_mobile_screen');

The SDK passes the declared surface along when it asks Active Reach which messages to show, and only renders a campaign whose surface matches.

Picking a surface on a campaign

Open the campaign in the editor and go to the Distribution step.
In the Surfaces card, leave All surfaces selected to show the message everywhere, or pick one or more surface chips to narrow it.
Selecting more than one surface uses OR logic — the message shows on any of the chosen surfaces.

If the campaign is also a standalone page (for example a rewards landing page), the matching surface is pre-selected and pinned — the page owns its surface, so the render guard has to match.

Brand-wide vs per-outlet

The chip strip at the top of the page is your scope picker:

All outlets — the campaign applies brand-wide, on its chosen surface, for every outlet.
A specific outlet — the campaign becomes a per-outlet override for just that store.

Surface and outlet are independent: you can have a brand-wide bill-only nudge, or a single-outlet bill-only nudge.

Filtering your list by surface

On the In-app messages list, use the Surface chip strip to show only the campaigns you scoped to a given surface. The selection lives in the page URL, so you can bookmark or share a filtered view.

Set up In-app messaging