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'sguidin SCAYLE), aname(the label in the SCAYLE Panel), and areferenceKey(the identifier you enter when you create the segment), all undercustomer.segmentson thecustomerprop. A shared prop is data every page receives. The groups of a customer arrive separately ascustomer.groups, and a segment rule can use a customer group as a criterion. - A check for a segment in code:
useCustomerinsrc/client/composables/useCustomer.tsreturnssegmentsandisInSegment(referenceKey)next to the customer. While thecustomerprop is still loading,segmentsisundefinedandisInSegmentreturnsundefined. AfterwardsisInSegmentreturnstruefor a member, andfalsefor a user and for a customer outside the segment. - A component that switches content by segment:
SFCustomerSegmentinsrc/client/components/account/SFCustomerSegment.vueswitches 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 therenderAllMatchingprop 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
promotionsprop 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_PROPSinsrc/shared/constants/segments.tslists the shared once props, which the browser keeps across visits, whose value you pick by segment.useAuthenticationadds 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
referenceKeyof each segment to the events of a signed-in customer ascustomer_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
SFCustomerSegmentslot is yours. Give it your own component, copy, and styling.
Extend
- Show a block to one customer segment with
SFCustomerSegment. - Show different content to users, customers, and segment members with
useCustomer. - Send segment-only data from a controller when the content must not reach anyone else.
- Hide a sort option from one customer segment in the product listing controller.
- Pick a shared once prop by segment, such as the header navigation. See Reload a shared prop that varies by customer segment.
Constraints and limits
Permanent
- A user without a customer ID is in no segment, so every
SFCustomerSegmentshows 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
defaultand the labelsorting_select.top_seller, which reads Recommendations inen_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
SFCustomerSegmentalso renders for a signed-in customer in none of the named segments and while thecustomerprop is loading. It cannot tell a user from a customer outside the segment. UseuseCustomerfor that, see Show different content to users, customers, and segment members. - A named slot that carries
v-if,v-else-if,v-else, orv-forcomes 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.
SFCustomerSegmentkeeps 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.segmentscan disagree with the promotions the same customer sees. - A customer whose request carries no
scayle-skip-cachecookie 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.segmentsstill lists the segments from sign-in. - Segment-targeted promotions are not in the server-rendered HTML, because the
promotionsprop 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
sortparameter 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 increateSortingOptionsreplaces 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
segmentsuntil the next sign-in. - A field you derive from
segmentsinCustomerMapperService.mapCustomer, such asisVip, is recomputed from the response of a profile update, and the SDK restores onlysegmentsitself from the session afterwards. That response carries no segments, so the derived field turnsfalseuntil the next sign-in. Compute such a flag in a component fromuseCustomerinstead.
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.
- 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. - 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.
| Setting | Where | Effect |
|---|---|---|
| Customer segment override | SCAYLE Panel, in the Smart Sorting Assignment of the shop or the shop country, or in the General Info of a category | Sets 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_PROPS | src/shared/constants/segments.ts | Lists 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.
- Add the translation key to
src/i18n/locales/en_GB.jsonand to every other locale file, see Translate a new key in all locales. - Import
SFCustomerSegmentinsrc/client/pages/ProductListing.vue. - Add the block above
SFProductGridin 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.
- Add the keys
product_detail_page.member_sign_inandproduct_detail_page.member_perkstosrc/i18n/locales/en_GB.jsonand to every other locale file, as in the first guide. - Create the component.
SFMemberBenefitsis a new file. It does not exist in the Storefront Application V3, and the name is only an example. - Import your new component in
src/client/pages/ProductDetail.vue. - Render it below
SFProductPricein 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.
- Return the prop from
getViewPropsinsrc/server/controllers/product-listing.ts. The file already importsInertiafrom@scayle/storefront. - Declare the prop in
src/client/pages/ProductListing.vue, and importDeferredandSFLink. - Add the translation key
product_list_page.early_accessto every locale file, then render the link insideDeferred.
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.
- Open
src/shared/constants/segments.ts. - 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
customerrequest has not answered yet.
The last two are described under Constraints and limits.
Solution:
- Compare the slot name with the reference key in the SCAYLE Panel.
- In the SCAYLE Panel, check that the customer matches the segment's rules.
- Sign out and sign in again, then reload the page.
- In the browser's storage panel, look for the
scayle-skip-cachecookie of the shop. Without it, wait for the deferredcustomerrequest 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
sortparameter, 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:
- 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.
- Open the category without a
sortparameter. - Check the order of the options in
createSortingOptions. - 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.