From de490a3ea7e5c309e44d78c6a93041bf8cecb5af Mon Sep 17 00:00:00 2001 From: Hao Li Date: Tue, 15 Jul 2025 23:01:36 -0400 Subject: [PATCH 1/3] Add analytics api on customer account ui extension doc --- .../reference/apis/analytics.doc.ts | 36 +++++++++++++++++++ .../apis/analytics-publish.example.ts | 31 ++++++++++++++++ .../apis/analytics-publish.example.tsx | 36 +++++++++++++++++++ .../apis/analytics-visitor.example.ts | 25 +++++++++++++ .../apis/analytics-visitor.example.tsx | 31 ++++++++++++++++ 5 files changed, 159 insertions(+) create mode 100644 packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts create mode 100644 packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.ts create mode 100644 packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.tsx create mode 100644 packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.ts create mode 100644 packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.tsx diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts new file mode 100644 index 0000000000..e61afab00c --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts @@ -0,0 +1,36 @@ +import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs'; + +const data: ReferenceEntityTemplateSchema = { + name: 'Analytics', + description: 'The API for interacting with web pixels.', + isVisualComponent: false, + category: 'APIs', + type: 'API', + definitions: [ + { + title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title, + description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description, + type: 'Docs_Standard_AnalyticsApi', + }, + ], + defaultExample: { + codeblock: { + title: 'Using a session token with fetch()', + tabs: [ + { + code: '../examples/apis/session-token.example.tsx', + language: 'jsx', + title: 'React', + }, + { + code: '../examples/apis/session-token.example.ts', + language: 'js', + title: 'JavaScript', + }, + ], + }, + }, + related: [], +}; + +export default data; diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.ts new file mode 100644 index 0000000000..d818d35b50 --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.ts @@ -0,0 +1,31 @@ +import {extension} from '@shopify/ui-extensions-react/customer-account'; +import {useEffect} from 'react'; + +export default extension( + 'purchase.checkout.block.render', + (root, {analytics}) => { + useEffect(() => { + analytics + .publish('checkout-extension-loaded', { + extensionName: 'My Extension', + }) + .then((result) => { + if (result) { + console.log( + 'succesfully published event, web pixels can now recieve this event', + ); + } else { + console.log( + 'failed to publish event', + ); + } + }) + .catch((error) => { + console.error( + 'failed to publish event', + ); + console.error('error', error); + }); + }); + }, +); diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.tsx b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.tsx new file mode 100644 index 0000000000..c2a498cea3 --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.tsx @@ -0,0 +1,36 @@ +import {useState, useEffect} from 'react'; +import { + Banner, + reactExtension, + useApi, +} from '@shopify/ui-extensions-react/customer-account'; + +export const purchaseCheckoutBlockRender = + reactExtension( + 'purchase.checkout.block.render', + () => , + ); + +function Extension() { + const {analytics} = useApi(); + + analytics + .publish('checkout-extension-loaded', { + extensionName: 'My Extension', + }) + .then((result) => { + if (result) { + console.log( + 'succesfully published event, web pixels can now recieve this event', + ); + } else { + console.log('failed to publish event'); + } + }) + .catch((error) => { + console.log('failed to publish event'); + console.log('error', error); + }); + + return See console for result; +} diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.ts new file mode 100644 index 0000000000..99be07b474 --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.ts @@ -0,0 +1,25 @@ +import {extension} from '@shopify/ui-extensions-react/customer-account'; + +export default extension( + 'purchase.checkout.block.render', + (root, {analytics}) => { + analytics + .visitor({ + email: 'someEmail@example.com', + phone: '+1 555 555 5555', + }) + .then((result) => { + if (result.type === 'success') { + console.log( + `Success`, + JSON.stringify(result), + ); + } else { + console.log( + `Error`, + JSON.stringify(result), + ); + } + }); + }, +); diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.tsx b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.tsx new file mode 100644 index 0000000000..94bc9cabcf --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.tsx @@ -0,0 +1,31 @@ +import {useState, useEffect} from 'react'; +import { + Banner, + reactExtension, + useApi, +} from '@shopify/ui-extensions-react/customer-account'; + +export const purchaseCheckoutBlockRender = + reactExtension( + 'purchase.checkout.block.render', + () => , + ); + +function Extension() { + const {analytics} = useApi(); + + analytics + .visitor({ + email: 'someEmail@example.com', + phone: '+1 555 555 5555', + }) + .then((result) => { + if (result.type === 'success') { + console.log('Success', result); + } else { + console.error('Error', result); + } + }); + + return See console for result; +} From bcde1b62b623e172c4dee19f6e2573c181903e05 Mon Sep 17 00:00:00 2001 From: Hao Li Date: Wed, 16 Jul 2025 16:49:11 -0400 Subject: [PATCH 2/3] fix error --- .../reference/apis/analytics.doc.ts | 29 +++++++++++++++++-- .../src/surfaces/customer-account/api/docs.ts | 3 ++ 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts index e61afab00c..c0e17ad050 100644 --- a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts @@ -1,3 +1,4 @@ +import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs'; const data: ReferenceEntityTemplateSchema = { @@ -18,18 +19,42 @@ const data: ReferenceEntityTemplateSchema = { title: 'Using a session token with fetch()', tabs: [ { - code: '../examples/apis/session-token.example.tsx', + code: '../examples/apis/analytics-publish.example.tsx', language: 'jsx', title: 'React', }, { - code: '../examples/apis/session-token.example.ts', + code: '../examples/apis/analytics-publish.example.ts', language: 'js', title: 'JavaScript', }, ], }, }, + examples: { + description: '', + examples: [ + { + description: + 'You can submit visitor information to Shopify, these will be sent to the shop backend and not be propagated to web pixels on the page.', + codeblock: { + title: 'Visitor', + tabs: [ + { + code: '../examples/apis/analytics-visitor.example.tsx', + language: 'jsx', + title: 'React', + }, + { + code: '../examples/apis/analytics-visitor.example.ts', + language: 'js', + title: 'JavaScript', + }, + ], + }, + }, + ], + }, related: [], }; diff --git a/packages/ui-extensions/src/surfaces/customer-account/api/docs.ts b/packages/ui-extensions/src/surfaces/customer-account/api/docs.ts index 604220d3d2..03c53b35e2 100644 --- a/packages/ui-extensions/src/surfaces/customer-account/api/docs.ts +++ b/packages/ui-extensions/src/surfaces/customer-account/api/docs.ts @@ -67,6 +67,9 @@ export interface Docs_Standard_LocalizationApi export interface Docs_Standard_SessionTokenApi extends Pick, 'sessionToken'> {} +export interface Docs_Standard_AnalyticsApi + extends Pick, 'analytics'> {} + export interface Docs_Standard_SettingsApi extends Pick {} From f59d2b6c9cb861cf5e96fc7c4f5a5d72526af7ff Mon Sep 17 00:00:00 2001 From: Hao Li Date: Thu, 17 Jul 2025 21:23:17 -0400 Subject: [PATCH 3/3] lint and notes --- .../reference/apis/analytics.doc.ts | 2 +- .../apis/analytics-publish.example.ts | 44 +++++++++---------- .../apis/analytics-publish.example.tsx | 14 +++--- .../apis/analytics-visitor.example.ts | 4 +- .../apis/analytics-visitor.example.tsx | 5 +-- .../api/standard-api/standard-api.ts | 2 + 6 files changed, 35 insertions(+), 36 deletions(-) diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts index c0e17ad050..69c0d59839 100644 --- a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts @@ -16,7 +16,7 @@ const data: ReferenceEntityTemplateSchema = { ], defaultExample: { codeblock: { - title: 'Using a session token with fetch()', + title: 'Publish', tabs: [ { code: '../examples/apis/analytics-publish.example.tsx', diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.ts index d818d35b50..23767937cf 100644 --- a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.ts +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.ts @@ -1,31 +1,27 @@ -import {extension} from '@shopify/ui-extensions-react/customer-account'; -import {useEffect} from 'react'; +import {extension} from '@shopify/ui-extensions/customer-account'; export default extension( - 'purchase.checkout.block.render', + 'customer-account.order-status.block.render', (root, {analytics}) => { - useEffect(() => { - analytics - .publish('checkout-extension-loaded', { + analytics + .publish( + 'customer-account-extension-loaded', + { extensionName: 'My Extension', - }) - .then((result) => { - if (result) { - console.log( - 'succesfully published event, web pixels can now recieve this event', - ); - } else { - console.log( - 'failed to publish event', - ); - } - }) - .catch((error) => { - console.error( - 'failed to publish event', + }, + ) + .then((result) => { + if (result) { + console.log( + 'succesfully published event, web pixels can now recieve this event', ); - console.error('error', error); - }); - }); + } else { + console.log('failed to publish event'); + } + }) + .catch((error) => { + console.error('failed to publish event'); + console.error('error', error); + }); }, ); diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.tsx b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.tsx index c2a498cea3..cd42835ea9 100644 --- a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.tsx +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.tsx @@ -1,13 +1,12 @@ -import {useState, useEffect} from 'react'; import { Banner, reactExtension, useApi, } from '@shopify/ui-extensions-react/customer-account'; -export const purchaseCheckoutBlockRender = +export const orderStatusBlockRender = reactExtension( - 'purchase.checkout.block.render', + 'customer-account.order-status.block.render', () => , ); @@ -15,9 +14,12 @@ function Extension() { const {analytics} = useApi(); analytics - .publish('checkout-extension-loaded', { - extensionName: 'My Extension', - }) + .publish( + 'customer-account-extension-loaded', + { + extensionName: 'My Extension', + }, + ) .then((result) => { if (result) { console.log( diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.ts index 99be07b474..711874c795 100644 --- a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.ts +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.ts @@ -1,7 +1,7 @@ -import {extension} from '@shopify/ui-extensions-react/customer-account'; +import {extension} from '@shopify/ui-extensions/customer-account'; export default extension( - 'purchase.checkout.block.render', + 'customer-account.order-status.block.render', (root, {analytics}) => { analytics .visitor({ diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.tsx b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.tsx index 94bc9cabcf..4f5d19fbd6 100644 --- a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.tsx +++ b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.tsx @@ -1,13 +1,12 @@ -import {useState, useEffect} from 'react'; import { Banner, reactExtension, useApi, } from '@shopify/ui-extensions-react/customer-account'; -export const purchaseCheckoutBlockRender = +export const orderStatusBlockRender = reactExtension( - 'purchase.checkout.block.render', + 'customer-account.order-status.block.render', () => , ); diff --git a/packages/ui-extensions/src/surfaces/customer-account/api/standard-api/standard-api.ts b/packages/ui-extensions/src/surfaces/customer-account/api/standard-api/standard-api.ts index c1142afe02..5867a8c062 100644 --- a/packages/ui-extensions/src/surfaces/customer-account/api/standard-api/standard-api.ts +++ b/packages/ui-extensions/src/surfaces/customer-account/api/standard-api/standard-api.ts @@ -82,6 +82,8 @@ export interface StandardApi { /** * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event. + * + * > Note: Requires to [connect a third-party domain](https://help.shopify.com/en/manual/domains/add-a-domain/connecting-domains/connect-domain-customer-account) to Shopify for your customer account pages. */ analytics: Analytics;