docs

Customer Segments

A customer segment contains the customers who match rules you define in the SCAYLE Panel, see Customer Segments. SCAYLE checks each customer against the rules. In the Storefront Application V3, the segments of a signed-in customer reach three things without storefront code: the promotions that target the segment, the default sort order on category pages, and the events that SCAYLE Analytics receives. A fourth, showing content to one segment, is yours to add with SFCustomerSegment, which no page uses until you do.

Why it matters

Your shop can tailor what customers see to the segments they belong to. Members get free returns, trade customers get a different shipping note, and a small group gets early access to a collection. Promotions already target segments in the SCAYLE Panel, so a segment-only promotion needs no storefront code, and so does a default sorting for a segment on a category page. Everything else a customer sees is your markup, and the segment tells you which version to show.

Cached pages are the same for every user, so a segment block can render a moment late. See How segments reach a page.

What's included

  • Segments on the customer: A signed-in customer carries the segments they belong to. Each entry has an id (the segment's guid in SCAYLE), a name (the label in the SCAYLE Panel), and a referenceKey (the identifier you enter when you create the segment), all under customer.segments on the customer prop. A shared prop is data every page receives. The groups of a customer arrive separately as customer.groups, and a segment rule can use a customer group as a criterion.
  • A check for a segment in code: useCustomer in src/client/composables/useCustomer.ts returns segments and isInSegment(referenceKey) next to the customer. While the customer prop is still loading, segments is undefined and isInSegment returns undefined. Afterwards isInSegment returns true for a member, and false for a user and for a customer outside the segment.
  • A component that switches content by segment: SFCustomerSegment in src/client/components/account/SFCustomerSegment.vue switches between blocks of markup. Each named slot is the reference key of a segment and renders when the customer belongs to it. The first matching slot wins, and the renderAllMatching prop renders every matching slot instead. Its slot types require a default slot, which renders for everyone else.
  • Segment-targeted promotions: A promotion that targets a segment reaches only the customers in it. While the access token is valid, the promotions prop and the basket send it, so the Storefront API returns and applies only the promotions the customer is eligible for. See Promotions.
  • Segment sorting on category pages: A customer in a segment with its own sorting sees that sorting as the default order on category pages. See How a segment changes the default sort.
  • A reload of segment-dependent props after sign-in and sign-out: SEGMENT_DEPENDENT_ONCE_PROPS in src/shared/constants/segments.ts lists the shared once props, which the browser keeps across visits, whose value you pick by segment. useAuthentication adds them to the reload after sign-in and reloads them after sign-out. The list ships empty.
  • Segments in SCAYLE Analytics events: The server adds the referenceKey of each segment to the events of a signed-in customer as customer_segments. See SCAYLE Analytics.

What you can change

Configure

  • Create segments and give each a reference key in the SCAYLE Panel under Customers, Customer Segments. See Setting Up a Customer Segment.
  • Target a promotion at one or more segments, or exclude segments from it, in the promotion's settings in the SCAYLE Panel. See Using Customer Segments.
  • Give a segment its own default sorting for a category, as a customer segment override on the shop, the shop country, or the shop country category in the SCAYLE Panel. See Customer Segment Overrides.

Theme

  • The markup inside each SFCustomerSegment slot is yours. Give it your own component, copy, and styling.

Extend

Constraints and limits

Permanent

  • A user without a customer ID is in no segment, so every SFCustomerSegment shows its default slot to a user. SCAYLE never matches such a user to a segment, which is also why segment-targeted promotions never show to them.
  • Only the category pages use a segment's sorting. Search and the recommendation sliders send no customer token, so their order is the same for every customer.
  • The default sort option keeps the key default and the label sorting_select.top_seller, which reads Recommendations in en_GB, whatever sorting the segment has. The dropdown does not show which sorting is behind it.
  • A signed-in customer's request skips the shared caches, and a category page costs more because its category and two navigation fetches skip the data cache when the customer has a valid access token. See Logged-in customers skip the shared cache and Rules for cached values.
  • The default slot of SFCustomerSegment also renders for a signed-in customer in none of the named segments and while the customer prop is loading. It cannot tell a user from a customer outside the segment. Use useCustomer for that, see Show different content to users, customers, and segment members.
  • A named slot that carries v-if, v-else-if, v-else, or v-for comes after the slots without one, because Vue compiles it separately. That order decides which slot wins when a customer matches several.
  • The markup in a template ships in the JavaScript bundle to every user who loads the page. SFCustomerSegment keeps a block out of the HTML of other users, and the bundle still holds it. Keep anything secret out of a template.

Known limitations

  • A change to a customer's segments in SCAYLE reaches the page only after the customer signs in again. The server reads the segments at sign-in and keeps them in the session. A profile update keeps them, and a token refresh does not read them again. The Storefront API checks the segments again for every promotion and basket request, so a block you switch by customer.segments can disagree with the promotions the same customer sees.
  • A customer whose request carries no scayle-skip-cache cookie can see the default content first and the segment content a moment later. Plan for the layout shift. See How segments reach a page.
  • A customer whose access token has expired gets no segment-targeted promotions, and gets the category and sorting an anonymous user gets. An expired access token counts as no token, while customer.segments still lists the segments from sign-in.
  • Segment-targeted promotions are not in the server-rendered HTML, because the promotions prop is deferred, so they appear after the page. The free-gift lookup on the product detail page sends no customer token. See Promotions.
  • The sorting of a segment is the default sort only. A link with an explicit sort parameter shows the same order to everyone. A user, a customer with an expired access token, and a cacheable render get the category's own default. An option you put first in createSortingOptions replaces it for every customer, see Add or reorder sort options.
  • A session without a segment list, for example one created before you updated the Storefront Application V3, gives an empty segments until the next sign-in.
  • A field you derive from segments in CustomerMapperService.mapCustomer, such as isVip, is recomputed from the response of a profile update, and the SDK restores only segments itself from the session afterwards. That response carries no segments, so the derived field turns false until the next sign-in. Compute such a flag in a component from useCustomer instead.

How it works

You define the segment rules in the SCAYLE Panel, and SCAYLE evaluates them for each customer. The Storefront Application V3 reads the result and decides what to render.

Where segments come from

At sign-in, the exchangeAuthCode procedure of @scayle/storefront fetches the customer from the Customer Account API, and the session stores it. The SDK's CustomerMapper maps the segments of that response, and your CustomerMapperService in src/server/services/mappers/customer-mapper.ts extends it and keeps them. A customer in the VIP Members segment looks like this:

The list is empty for a customer in no segment. A customer can belong to several segments at once.

How segments reach a page

shareCustomer in src/server/middleware/sharedData.ts decides how the customer prop arrives. A request for a page the response cache stores reads no session. A signed-in customer's request carries the scayle-skip-cache cookie, goes to your server instead, and gets the customer prop with the page, so the segment slot renders on the server. A request without the cookie gets the cached page with a deferred customer prop. The default slot renders first, and a partial reload swaps in the segment slot for a customer. A user gets null and keeps the default slot. See Logged-in customers skip the shared cache for the cookie and How cacheable routes deliver per-customer basket and user data for the deferred request. Props and when they load explains the prop forms.

How a segment changes the default sort

You set the sorting per segment in the SCAYLE Panel, and the Storefront Application V3 passes the customer's token on. For a customer, SCAYLE picks one sorting: the first override, by priority, whose segment the customer belongs to, or the category's default when none matches. See Customer Segment Overrides for the levels you can set it on, the priority order, and the rules.

The category the page receives carries that sorting, and CategoryMapper turns it into category.defaultSortingOption. For a segment override with a smart sorting key, it looks like this:

createSortingOptions puts that option first. The page selects the first option when the sort query parameter is missing or matches no option, so a customer who opens the category without sort gets the segment's order. The product query then sends the option's config to the Storefront API. It carries no customer token, and its data cache key includes the sorting. Segments with different sorting keys use different cache entries, and segments with the same key share one.

Setup

The segment support ships in the Storefront Application V3, so the setup happens in the SCAYLE Panel.

  1. Create a segment under Customers, Customer Segments, and enter a reference key that your code will compare, for example vip-members. See Setting Up a Customer Segment.
  2. Pick a test customer that matches the segment's rules.

You know it worked when the segment is listed under Customers, Customer Segments with the reference key you chose. The first guide below shows the segment on a page.

Configuration

The Storefront Application V3 has no environment variable or storefront.config.ts option for segments.

SettingWhereEffect
Customer segment overrideSCAYLE Panel, in the Smart Sorting Assignment of the shop or the shop country, or in the General Info of a categorySets the default sorting for a segment on the shop, the shop country, or the shop country category. The Storefront Application V3 shows it on category pages as the default sort. See Customer Segment Overrides.
SEGMENT_DEPENDENT_ONCE_PROPSsrc/shared/constants/segments.tsLists the shared once props that useAuthentication adds to the reload after sign-in and reloads after sign-out. The list ships empty, and an empty list adds nothing to the sign-in reload and skips the sign-out reload.

Customization guides

Each guide says when it asks you to create a new file or a new component. Every other component and composable in the snippets already exists in the Storefront Application V3.

Show a block to one customer segment

You end up with a note that customers in the vip-members segment see above the product grid of every category page, and that nobody else sees. The guide uses the existing SFCustomerSegment and plain markup, and creates no new component. The same steps work on the product detail page.

Prerequisite: a segment with the reference key vip-members and a test customer in it, see Setup.

  1. Add the translation key to src/i18n/locales/en_GB.json and to every other locale file, see Translate a new key in all locales.
  2. Import SFCustomerSegment in src/client/pages/ProductListing.vue.
  3. Add the block above SFProductGrid in the template. The slot name is the reference key, and the empty default slot renders nothing for everyone else.

You know it worked when the test customer sees the note in the page source of the first response, provided the request carries the skip-cache cookie, and a user sees no note. A customer whose request lacks the cookie sees it a moment later, see Constraints and limits.

Show different content to users, customers, and segment members

You end up with a new component, SFMemberBenefits, on the product detail page that asks a user to sign in, shows perks to customers in the vip-members segment, and shows nothing to other customers. SFCustomerSegment cannot do this alone, because its default slot serves users and customers outside the segment alike.

Prerequisite: a segment with the reference key vip-members, see Setup.

useCustomer tells the three states apart: undefined while the customer prop loads, null for a user, and an object for a customer.

  1. Add the keys product_detail_page.member_sign_in and product_detail_page.member_perks to src/i18n/locales/en_GB.json and to every other locale file, as in the first guide.
  2. Create the component. SFMemberBenefits is a new file. It does not exist in the Storefront Application V3, and the name is only an example.
  3. Import your new component in src/client/pages/ProductDetail.vue.
  4. Render it below SFProductPrice in the template.

You know it worked when a user sees the sign-in link, a customer in the segment sees the perks, and a customer outside it sees nothing. On a cacheable page the loading state renders nothing, so a user sees the link only after the deferred customer request answers.

Send segment-only data from a controller

You end up with a link to an early-access collection that only customers in the early-access segment receive. The guide creates no new component. It adds a new page prop, earlyAccessPath, and the path in the snippet is an example, so use the path of your own collection. The link is in no response to anyone else. Use this when the data itself must stay private, because markup in a slot does not, see Constraints and limits.

Prerequisite: a segment with the reference key early-access, see Setup.

The callback of a deferred prop runs in a partial reload. The response cache marks a partial reload as not cacheable, and the session middleware loads the session for it, so the callback can read the customer. It returns null for everyone else, because Inertia drops undefined from the response. See Defer slow data for declaring the prop optional.

  1. Return the prop from getViewProps in src/server/controllers/product-listing.ts. The file already imports Inertia from @scayle/storefront.
  2. Declare the prop in src/client/pages/ProductListing.vue, and import Deferred and SFLink.
  3. Add the translation key product_list_page.early_access to every locale file, then render the link inside Deferred.

You know it worked when a customer in the segment sees the link a moment after the page loads, and the link appears in no response for a user or a customer outside the segment. The prop arrives in the follow-up request for the group customer, so the link is never in the first response.

Reload a shared prop that varies by customer segment

You end up with a shared prop that shows the right value right after a sign-in or sign-out, for a prop you pick by customer segment. A once prop is a shared prop the browser keeps across visits, see Props and when they load. Without this step the previous customer's value stays until a full page load.

Prerequisite: a once prop in src/server/middleware/sharedData.ts whose value your shop picks by customer segment, such as the header navigation.

  1. Open src/shared/constants/segments.ts.
  2. Add the prop key to SEGMENT_DEPENDENT_ONCE_PROPS.

You know it worked when the partial reload that follows a sign-in requests the prop, and the prop carries the new customer's value without a page refresh. The snippet shows the list with your prop added, and the shipped list is empty. With an empty list, the default reload covers only customer, basket, wishlist, and promotions.

Best practices

Compare reference keys

The name is a label that anyone with access can rename in the SCAYLE Panel. The referenceKey is the identifier you chose for integrations. The SCAYLE Panel lets you edit it too, so keep it unchanged once your code depends on it.

Give the default slot real content

On a cacheable page the default slot is what the first paint shows. An empty default shifts the layout when a large segment block arrives. Reserve the space, or make the default a shorter version of the same content, such as a returns note that reads 30 days for everyone and 100 days for the segment.

Use a promotion for a member price

A segment decides what you show. The Storefront API applies the promotions for the customer, and the storefront displays the reduction without calculating it. Target a promotion at the segment in the SCAYLE Panel instead of computing a member price in a component.

Troubleshooting

A customer in the segment sees the default slot

Issue: A named slot does not render for a customer you know is in the segment, and the default slot shows instead.

Possible causes:

  • The slot name differs from the segment's reference key. The comparison is exact, so letter case and hyphens count.
  • The customer does not match the segment's rules in SCAYLE.
  • The session holds the segments from an earlier sign-in, or none.
  • The page came from the response cache, and the deferred customer request has not answered yet.

The last two are described under Constraints and limits.

Solution:

  1. Compare the slot name with the reference key in the SCAYLE Panel.
  2. In the SCAYLE Panel, check that the customer matches the segment's rules.
  3. Sign out and sign in again, then reload the page.
  4. In the browser's storage panel, look for the scayle-skip-cache cookie of the shop. Without it, wait for the deferred customer request and look again.

Prevention: Copy the reference key from the SCAYLE Panel instead of typing it, and sign in again after you change a segment while you test.

The default sort does not change for a customer in the segment

Issue: A customer in a segment with its own sorting sees the same product order as a user.

Possible causes:

  • No override on the category's level matches the segment, or the level has no default sorting. A level that sets a sorting of its own does not inherit overrides from the levels above.
  • The URL carries an explicit sort parameter, or your controller puts another option first.
  • The request carries no valid access token, or the page came from the response cache. See Known limitations under Constraints and limits.

Solution:

  1. In the SCAYLE Panel, find the nearest level with a sorting of its own, starting at the shop country category, then the shop country, then the shop, and check that the segment is on its list of overrides. See Customer Segment Overrides.
  2. Open the category without a sort parameter.
  3. Check the order of the options in createSortingOptions.
  4. Sign out and sign in again so the session holds a valid access token, then reload the page.

Prevention: Test with a category URL without sort and with a customer who has just signed in.

Reference

Customer Account API

SCAYLE Panel configuration