Add analytics api on 2025-07 customer account ui extension doc

packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts

@@ -0,0 +1,61 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+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: 'Publish',
+      tabs: [
+        {
+          code: '../examples/apis/analytics-publish.example.tsx',
+          language: 'jsx',
+          title: 'React',
+        },
+        {
+          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: [],
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.ts

@@ -0,0 +1,27 @@
+import {extension} from '@shopify/ui-extensions/customer-account';
+
+export default extension(
+  'customer-account.order-status.block.render',
+  (root, {analytics}) => {
+    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');
+        console.error('error', error);
+      });
+  },
+);

packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.tsx

@@ -0,0 +1,38 @@
+import {
+  Banner,
+  reactExtension,
+  useApi,
+} from '@shopify/ui-extensions-react/customer-account';
+
+export const orderStatusBlockRender =
+  reactExtension(
+    'customer-account.order-status.block.render',
+    () => <Extension />,
+  );
+
+function Extension() {
+  const {analytics} = useApi();
+
+  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.log('failed to publish event');
+      console.log('error', error);
+    });
+
+  return <Banner>See console for result</Banner>;
+}

packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.ts

@@ -0,0 +1,25 @@
+import {extension} from '@shopify/ui-extensions/customer-account';
+
+export default extension(
+  'customer-account.order-status.block.render',
+  (root, {analytics}) => {
+    analytics
+      .visitor({
+        email: '[email protected]',
+        phone: '+1 555 555 5555',
+      })
+      .then((result) => {
+        if (result.type === 'success') {
+          console.log(
+            `Success`,
+            JSON.stringify(result),
+          );
+        } else {
+          console.log(
+            `Error`,
+            JSON.stringify(result),
+          );
+        }
+      });
+  },
+);

packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-visitor.example.tsx

@@ -0,0 +1,30 @@
+import {
+  Banner,
+  reactExtension,
+  useApi,
+} from '@shopify/ui-extensions-react/customer-account';
+
+export const orderStatusBlockRender =
+  reactExtension(
+    'customer-account.order-status.block.render',
+    () => <Extension />,
+  );
+
+function Extension() {
+  const {analytics} = useApi();
+
+  analytics
+    .visitor({
+      email: '[email protected]',
+      phone: '+1 555 555 5555',
+    })
+    .then((result) => {
+      if (result.type === 'success') {
+        console.log('Success', result);
+      } else {
+        console.error('Error', result);
+      }
+    });
+
+  return <Banner>See console for result</Banner>;
+}

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<StandardApi<any>, 'sessionToken'> {}
 
+export interface Docs_Standard_AnalyticsApi
+  extends Pick<StandardApi<any>, 'analytics'> {}
+
 export interface Docs_Standard_SettingsApi
   extends Pick<StandardApi, 'settings'> {}
 

packages/ui-extensions/src/surfaces/customer-account/api/standard-api/standard-api.ts

@@ -82,6 +82,8 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
 
   /**
    * 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;