Add appEvents.emit to the Checkout and Customer Account APIs

.changeset/app-events-checkout-customer-account.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+`appEvents`: add `shopify.appEvents.emit(eventHandle, attributes?)` to the Checkout standard and address-autocomplete APIs and the Customer Account standard API, for reporting app events to Shopify

packages/ui-extensions-tester/src/checkout/factories.ts

@@ -39,6 +39,7 @@ function createSharedApiMocks() {
       visitor: async () => ({type: 'success' as const}),
     },
     i18n: createMockI18n(),
+    appEvents: {emit: async () => ({success: true as const})},
     sessionToken: {get: async () => 'mock-session-token'},
     shop: {
       id: 'gid://shopify/Shop/1',

packages/ui-extensions-tester/src/customer-account/factories.ts

@@ -51,6 +51,7 @@ function createStandardApiProperties<T extends ExtensionTarget>(target: T) {
     },
     i18n: createMockI18n(),
     storage: createStorage(),
+    appEvents: {emit: async () => ({success: true as const})},
     sessionToken: {get: async () => 'mock-session-token'},
     analytics: {
       publish: async () => true,

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

@@ -27,6 +27,10 @@ export type {
   Shop,
   Version,
   Metafield,
+  AppEventAttributeValue,
+  AppEventAttributes,
+  AppEventEmitResult,
+  AppEvents,
   AppMetafield,
   AppMetafieldEntryTarget,
   AppMetafieldEntry,

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

@@ -1,5 +1,6 @@
 import type {
   Analytics,
+  AppEvents,
   AppMetafieldEntry,
   Capability,
   CheckoutToken,
@@ -48,6 +49,11 @@ export interface AddressAutocompleteStandardApi<
    */
   analytics: Analytics;
 
+  /**
+   * Reports events to Shopify for this app.
+   */
+  appEvents: AppEvents;
+
   /**
    * The custom attributes left by the customer to the merchant, either in their cart or during checkout.
    */

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

@@ -584,6 +584,11 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   analytics: Analytics;
 
+  /**
+   * Reports events to Shopify for this app.
+   */
+  appEvents: AppEvents;
+
   /**
    * The gift cards that have been applied to the checkout. Each entry includes
    * the last four characters of the gift card code, the amount used at
@@ -1690,6 +1695,51 @@ export interface Analytics {
    */
   visitor(data: {email?: string; phone?: string}): Promise<VisitorResult>;
 }
+
+/**
+ * A value attached to an app event.
+ * @publicDocs
+ */
+export type AppEventAttributeValue = string | number | boolean;
+
+/**
+ * Attributes related to an app event.
+ * @publicDocs
+ */
+export type AppEventAttributes = Record<string, AppEventAttributeValue>;
+
+/**
+ * The outcome of an `emit` call.
+ *
+ * `success: true` means the host accepted the event. It does not confirm delivery.
+ *
+ * `success: false` means the event was not sent. `error` describes why.
+ * @publicDocs
+ */
+export type AppEventEmitResult =
+  | {readonly success: true}
+  | {readonly success: false; readonly error: string};
+
+/**
+ * Reports events to Shopify for this app.
+ * @publicDocs
+ */
+export interface AppEvents {
+  /**
+   * Reports one occurrence of an app-defined event.
+   *
+   * @param eventHandle The app-defined event name.
+   * @param attributes Attributes related to this event.
+   *   @default {}
+   * @returns A promise that resolves with the outcome once the host has
+   *   handled the call.
+   */
+  emit(
+    eventHandle: string,
+    attributes?: AppEventAttributes,
+  ): Promise<AppEventEmitResult>;
+}
+
 /**
  * Represents a visitor result.
  * @publicDocs

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

@@ -79,6 +79,10 @@ export type {
   VisitorSuccess,
   VisitorError,
   SubscribableSignalLike,
+  AppEventAttributeValue,
+  AppEventAttributes,
+  AppEventEmitResult,
+  AppEvents,
 } from './api/shared';
 
 export type {CartLineItemApi} from './api/cart-line/cart-line-item';

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

@@ -11,6 +11,12 @@ import type {
 } from '../../../shared';
 
 import type {SubscribableSignalLike} from '../../checkout/shared';
+import type {
+  AppEventAttributeValue,
+  AppEventAttributes,
+  AppEventEmitResult,
+  AppEvents,
+} from '../../checkout/api/standard/standard';
 
 export {
   ApiVersion,
@@ -21,6 +27,10 @@ export {
   GraphQLError,
   StorefrontApiVersion,
   SubscribableSignalLike,
+  AppEventAttributeValue,
+  AppEventAttributes,
+  AppEventEmitResult,
+  AppEvents,
 };
 
 /**

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

@@ -14,6 +14,7 @@ import {
   ToastApi,
   Intents,
   SubscribableSignalLike,
+  AppEvents,
 } from '../shared';
 
 import type {ExtensionTarget} from '../../extension-targets';
@@ -78,6 +79,11 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   sessionToken: SessionToken;
 
+  /**
+   * Reports events to Shopify for this app.
+   */
+  appEvents: AppEvents;
+
   /**
    * Tracks custom events and sends visitor information to [web pixels](/docs/apps/build/marketing-analytics/pixels). Use `publish()` to emit events and `visitor()` to submit visitor data.
    *