Segmentation / Introduce `CustomerSegmentationTemplate` component #759

loic-d · 2023-02-22T20:11:00Z

Background

Fixes https://github.com/Shopify/core-issues/issues/51784
We are building a new rendering UI extension for Customer Segmentation. We're introducing a new component called CustomerSegmentationTemplate that will be used to render segmentation templates in the Admin:

Solution

This PR adds the required interfaces for CustomerSegmentationTemplate in @shopify/ui-extensions/admin and @shopify/ui-extensions-react/admin. See code examples in PR.

🎩

🍏 CI. You can also generate a build (yarn build) and consume these new changes in your app extension.

Checklist

I have 🎩'd these changes
I have updated relevant documentation

packages/ui-extensions-react/src/surfaces/admin.ts

...ions/src/surfaces/admin/api/customer-segmentation-template/customer-segmentation-template.ts

henrytao-me

Code looks good 👍

packages/ui-extensions/src/surfaces/admin/shared.ts

...ions/src/surfaces/admin/api/customer-segmentation-template/customer-segmentation-template.ts

packages/ui-extensions-react/src/surfaces/admin.ts

...s/src/surfaces/admin/components/CustomerSegmentationTemplate/CustomerSegmentationTemplate.ts

lemonmade · 2023-02-23T20:44:31Z

packages/ui-extensions/src/surfaces/admin/extension-points.ts


 export interface ExtensionPoints {
  Playground: RenderExtension<StandardApi<'Playground'>, AnyComponent>;
+  'Admin::Customers::SegmentationTemplatesFirstTimeBuyers::Show': RenderExtension<


Why did we choose to do separate extension points for each of these, rather than the context being passed in as part of the extension API?

@lemonmade we just haven't thought about it. currently, each extension point maps to a category of templates.

Our extension could accept a templateCategory parameter as part of the API and return the right templates accordingly. This would also solve the problem of the "all" category. We'd have to run the extension for each category (instead of running extensions for each extension point).

How does that sound? Would you also use a union type instead of an enum to represent the categories?

Does that mean that the extension has to handle all categories? What happens if they don't? We'd just get a blank extension with no way to tell that it's blank no?

We (Segmentation app) have to handle all categories. Admin will loop over a list of categories and render the extension with the current category as api. If our extension doesn't handle a category, the page will be blank. We'll make sure to handle all categories. This is maybe where a non-rendering extension could have been matter because we could have returned a map of templates where the key is the category.

For other 1P (Shopify Email, etc.) and 3P apps, their templates will be grouped under an "Apps" entry point. We will provide apps as category but they can basically ignore it.

I think it would be very messy to go down the route of passing them a category they might ignore. It would result in the wrong template being shown for the category or blank content. It actually seems a lot better to separate these to different extension points they can specifically opt in to use.

The category is really just for us. Can we have different private and public APIs?
On the Admin side we were thinking of populating categories just for our app (app ID or handle lookup).
Any other extension should go to the Apps category and the provided templateCategory doesn't matter.

We discussed on Slack, TLDR: we don't know yet how/if categories will be used by 3P. It makes sense to keep things simple for now with a single extension point and the templateCategory passed in as a starting point. We can evolve this later

lemonmade · 2023-02-23T20:46:45Z

packages/ui-extensions/src/surfaces/admin/extension-points.ts


 export interface ExtensionPoints {
  Playground: RenderExtension<StandardApi<'Playground'>, AnyComponent>;
+  'Admin::Customers::SegmentationTemplatesFirstTimeBuyers::Show': RenderExtension<


Are we going to wait until the conventions for extension point names is sorted out? Show is a term that they are using in that proposal currently, but it is different from checkout and I am not sure we have alignment on that part of the naming proposal.

I looped in @MeredithCastile. Like you suggested, we might even be able to merge all our extension points.

I'm thinking it could be admin.customers.segmentation-templates.show. This could be used by both our Admin Templates app, and 1P + 3P apps 🤔

lemonmade · 2023-02-23T20:48:52Z

...ions/src/surfaces/admin/api/customer-segmentation-template/customer-segmentation-template.ts

+import type {StandardApi} from '../standard/standard';
+import type {ExtensionPoint as AnyExtensionPoint} from '../../extension-points';
+
+export enum CustomerSegmentationFeature {


I think there needs to be some documentation about what these are.

I can add more context. These are internal feature flags for our own Segmentation templates. Other 3P apps shouldn't rely on them and only use QL public features.

Once we open this to 3Ps, can we expose a new API interface without this property?

...ions/src/surfaces/admin/api/customer-segmentation-template/customer-segmentation-template.ts

lemonmade · 2023-02-23T20:50:30Z

...ions/src/surfaces/admin/api/customer-segmentation-template/customer-segmentation-template.ts

+  ExtensionPoint extends AnyExtensionPoint,
+> extends StandardApi<ExtensionPoint> {
+  /** List of enabled segmentation query language features. */
+  enabledFeatures: [CustomerSegmentationFeature];


This is a guaranteed, single-item array of enabledFeatures — is this what you are after? I assume you at least want this to be CustomerSegmentationFeature[] instead.

However, is there no chance this list will ever change at runtime? In checkout, we already wrap all "read" APIs like this in a "subscribable" object that gives us the surface area to let them change over time (and to give partners a consistent API for subscribing to changeable data).

As you can see, my code is rusty 😄

CustomerSegmentationFeature[] is what we need.

All these features map to a beta flag in Core. I guess the list of features could change at run-time if we trigger a refetch of the component's GQL query (wrapping the extension) and pull the updated beta flag values.

packages/ui-extensions/src/shared.ts

loic-d · 2023-02-23T22:19:50Z

...in/components/CustomerSegmentationTemplate/examples/CustomerSegmentationTemplate.example.tsx

+} from '@shopify/ui-extensions-react/admin';
+
+function App({i18n, enabledFeatures, category}) {
+  if (category !== 're_engage_customers') {


cc/ @jonathanhamel4

loic-d · 2023-02-23T22:47:47Z

packages/ui-extensions/src/surfaces/checkout/api.ts

@@ -1,3 +1,4 @@
+export type {I18n, I18nTranslate} from '../../shared';


We're now re-exporting these types from the shared utility

loic-d · 2023-02-23T22:56:37Z

@vividviolet @lemonmade this is ready for a second review:

move I18n to a shared file for both checkout and admin surfaces
use a single extension point (admin.customers.segmentation-templates.render) and provide the template category as part of the api. Meredith is on board 👍
use union type instead of enums
improve examples and inline comments

the outstanding question is for enabledFeatures. these are really meant to be temporary (weeks) while we rollout new features. they shouldn't be used by 1P or 3P apps other than our own Segmentation app. once we address some technical limitations on our customer data platform, we shouldn't even need them anymore. are you ok with the approach I took in this PR?

lemonmade · 2023-02-24T18:17:09Z

packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts

-/**
- * This defines the i18n.translate() signature.
- */
-export interface I18nTranslate {


@kumar303 @marvinhagemeister do you know if any of the docs extraction stuff is depending on the exact file structure of our packages? This is on the shared UI extension package, so it won't impact checkout yet, but we will need to make sure it works as part of versioning.

vividviolet

👍

…nsions-react Adds changeset Updates comment Fixes typo Moves CustomerSegmentationTemplateComponent to extension-points file Moves I18n to shared utility, Renamed extension points Properly re-export I18n and I18nTranslate Fixes examples, Renames prop to icon Uses a type instead of an enum. Adds comments on enabled features Drops Polaris from comment Uses single extension point Returns null Better examples Fixes conditional in example Fixes QL string in examples Uses render instead of show Marks enabledFeatures as private and add __ prefix Moves I18n to API Uses camelCase for categories, Make categories private Uses camelCase for enabled features type

This comment has been minimized.

Sign in to view

loic-d requested review from vividviolet and lemonmade February 22, 2023 21:10

loic-d commented Feb 22, 2023

View reviewed changes

packages/ui-extensions-react/src/surfaces/admin.ts Outdated Show resolved Hide resolved

loic-d commented Feb 22, 2023

View reviewed changes

...ions/src/surfaces/admin/api/customer-segmentation-template/customer-segmentation-template.ts Show resolved Hide resolved

loic-d removed request for lemonmade and vividviolet February 23, 2023 15:14

henrytao-me approved these changes Feb 23, 2023

View reviewed changes

loic-d requested review from jonathanhamel4 and carolopolo February 23, 2023 16:38

vividviolet reviewed Feb 23, 2023

View reviewed changes

lemonmade reviewed Feb 23, 2023

View reviewed changes

loic-d commented Feb 23, 2023

View reviewed changes

packages/ui-extensions/src/shared.ts Outdated Show resolved Hide resolved

loic-d commented Feb 23, 2023

View reviewed changes

lemonmade approved these changes Feb 24, 2023

View reviewed changes

vividviolet approved these changes Feb 24, 2023

View reviewed changes

loic-d force-pushed the ld/customer-segmentation-template branch from 55c3cc0 to 2174598 Compare February 24, 2023 18:39

loic-d force-pushed the ld/customer-segmentation-template branch from 2174598 to 4e71987 Compare February 24, 2023 18:58

loic-d merged commit fa57c5d into unstable Feb 24, 2023

shopify-github-actions-access bot mentioned this pull request Jun 2, 2023

Version Packages (2022-10) #988

Open

shopify-github-actions-access bot mentioned this pull request Jul 17, 2023

Version Packages (2023-04) #1092

Merged

shopify-github-actions-access bot mentioned this pull request Jul 25, 2023

Version Packages (2023-07) #1155

Merged

lauramann mentioned this pull request Aug 14, 2023

Adds CustomerSegmentTemplate component #1226

Merged

2 tasks

shopify-github-actions-access bot mentioned this pull request Oct 2, 2023

Version Packages (2023-10) #1406

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Segmentation / Introduce `CustomerSegmentationTemplate` component #759

Segmentation / Introduce `CustomerSegmentationTemplate` component #759

loic-d commented Feb 22, 2023 •

edited by jonathanhamel4

Loading

This comment has been minimized.

henrytao-me left a comment

lemonmade Feb 23, 2023

loic-d Feb 23, 2023

vividviolet Feb 24, 2023

loic-d Feb 24, 2023

vividviolet Feb 24, 2023

loic-d Feb 24, 2023

vividviolet Feb 24, 2023

lemonmade Feb 23, 2023

loic-d Feb 23, 2023

lemonmade Feb 23, 2023

loic-d Feb 23, 2023

lemonmade Feb 23, 2023

loic-d Feb 23, 2023 •

edited

Loading

loic-d Feb 23, 2023

loic-d Feb 23, 2023

loic-d commented Feb 23, 2023 •

edited

Loading

lemonmade Feb 24, 2023

vividviolet left a comment

		@@ -1,3 +1,4 @@
		export type {I18n, I18nTranslate} from '../../shared';

Segmentation / Introduce CustomerSegmentationTemplate component #759

Segmentation / Introduce CustomerSegmentationTemplate component #759

Conversation

loic-d commented Feb 22, 2023 • edited by jonathanhamel4 Loading

Background

Solution

🎩

Checklist

This comment has been minimized.

henrytao-me left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

loic-d Feb 23, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

loic-d commented Feb 23, 2023 • edited Loading

Choose a reason for hiding this comment

vividviolet left a comment

Choose a reason for hiding this comment

Segmentation / Introduce `CustomerSegmentationTemplate` component #759

Segmentation / Introduce `CustomerSegmentationTemplate` component #759

loic-d commented Feb 22, 2023 •

edited by jonathanhamel4

Loading

loic-d Feb 23, 2023 •

edited

Loading

loic-d commented Feb 23, 2023 •

edited

Loading