diff --git a/astro.sidebar.mjs b/astro.sidebar.mjs index 3dddcd1ff..fd2741350 100644 --- a/astro.sidebar.mjs +++ b/astro.sidebar.mjs @@ -165,9 +165,9 @@ export function generateSidebar() { { label: 'AEM Assets Integration', link: '/setup/configuration/aem-assets-configuration/' }, { label: 'AEM Commerce Prerender', link: '/setup/configuration/aem-prerender/' }, { label: 'Content Delivery Network', link: '/setup/configuration/content-delivery-network/' }, + { label: 'Gated Content', link: '/setup/configuration/gated-content/' }, { label: 'CORS Setup', link: '/setup/configuration/cors-setup/' }, { label: 'CORS Troubleshooting', link: '/setup/configuration/cors-troubleshooting/' }, - { label: 'Gated Content', link: '/setup/configuration/gated-content/' }, { label: 'Data Export Validation', link: '/setup/discovery/data-export-validation/' }, ], }, @@ -466,6 +466,9 @@ export function generateSidebar() { { label: 'PaymentMethods', link: '/dropins/user-account/containers/payment-methods/', }, + { label: 'Seller-Assisted Buying', link: '/dropins/user-account/containers/seller-assisted-buying/' }, + { label: 'SellerAssistedBuyingActivity', link: '/dropins/user-account/containers/seller-assisted-buying-activity/' }, + { label: 'SellerAssistedBuyingSettings', link: '/dropins/user-account/containers/seller-assisted-buying-settings/' }, ], }, ], @@ -876,6 +879,7 @@ export function generateSidebar() { { label: 'Return Header', link: '/merchants/blocks/commerce-return-header/' }, { label: 'Returns List', link: '/merchants/blocks/commerce-returns-list/' }, { label: 'Search Order', link: '/merchants/blocks/commerce-search-order/' }, + { label: 'Seller-Assisted Buying', link: '/merchants/blocks/seller-assisted-buying/' }, { label: 'Shipping Status', link: '/merchants/blocks/commerce-shipping-status/' }, { label: 'Wishlist', link: '/merchants/blocks/commerce-wishlist/' }, { label: 'Product Details', link: '/merchants/blocks/product-details/' }, diff --git a/public/images/dropins/SAB-Boilerplate.png b/public/images/dropins/SAB-Boilerplate.png new file mode 100644 index 000000000..10839c2a6 Binary files /dev/null and b/public/images/dropins/SAB-Boilerplate.png differ diff --git a/public/images/dropins/SAB-OrderStatus.png b/public/images/dropins/SAB-OrderStatus.png new file mode 100644 index 000000000..34bd1d019 Binary files /dev/null and b/public/images/dropins/SAB-OrderStatus.png differ diff --git a/public/images/dropins/SAB-OrdersList.png b/public/images/dropins/SAB-OrdersList.png new file mode 100644 index 000000000..fecaf185b Binary files /dev/null and b/public/images/dropins/SAB-OrdersList.png differ diff --git a/public/images/dropins/SAB-Settings.png b/public/images/dropins/SAB-Settings.png new file mode 100644 index 000000000..fc03352a0 Binary files /dev/null and b/public/images/dropins/SAB-Settings.png differ diff --git a/public/images/dropins/SAB-SignUp.png b/public/images/dropins/SAB-SignUp.png new file mode 100644 index 000000000..fb2eede68 Binary files /dev/null and b/public/images/dropins/SAB-SignUp.png differ diff --git a/public/images/dropins/SAB-log.png b/public/images/dropins/SAB-log.png new file mode 100644 index 000000000..b0900828b Binary files /dev/null and b/public/images/dropins/SAB-log.png differ diff --git a/src/content/docs/dropins/all/introduction.mdx b/src/content/docs/dropins/all/introduction.mdx index 400e520bd..a6080fc11 100644 --- a/src/content/docs/dropins/all/introduction.mdx +++ b/src/content/docs/dropins/all/introduction.mdx @@ -98,4 +98,4 @@ The table below shows every approach with links to the details. ## What's next -You now know what every drop-in is made of, and which ones are available. The next step is writing the code. [Using drop-ins](/dropins/all/quick-start/) shows the three-line pattern — import the initializer, import a container, render it with a complete working example. +You now know what every drop-in is made of, and which ones are available. The next step is writing the code. [Using drop-ins](/dropins/all/quick-start/) shows the three-line pattern — import the initializer, import a container, render it with a complete working example. diff --git a/src/content/docs/dropins/order/containers/order-status.mdx b/src/content/docs/dropins/order/containers/order-status.mdx index 3e45a85d7..b23539d63 100644 --- a/src/content/docs/dropins/order/containers/order-status.mdx +++ b/src/content/docs/dropins/order/containers/order-status.mdx @@ -7,6 +7,7 @@ sidebar: import { Aside } from '@astrojs/starlight/components'; import TableWrapper from '@components/TableWrapper.astro'; +import Diagram from '@components/Diagram.astro'; @@ -62,5 +63,17 @@ await provider.render(OrderStatus, { })(block); ``` +## Administrator-assisted orders + +When the seller-assisted buying feature is in use, the `OrderStatus` container shows an "Order placed by an administrator" label when `adminAssistedOrder` is set on the order. The label renders with the CSS class `.order-order-status-content__admin-assisted` and appears automatically. No configuration is required. + + + ![Order status page showing the administrator label](@images/dropins/SAB-OrderStatus.png) + + +To customize the label text, override the `Order.OrderStatusContent.adminAssistedLabel` dictionary key in the order initializer. See the [Order dictionary](/dropins/order/dictionary/) for the key and [Seller-assisted buying](/dropins/user-account/containers/seller-assisted-buying/) for the end-to-end flow. + +{/* Verified against adobe-commerce/storefront-order src/components/OrderStatusContent/OrderStatusContent.tsx: adminAssistedOrder (boolean), label key Order.OrderStatusContent.adminAssistedLabel, CSS class .order-order-status-content__admin-assisted; src/i18n/en_US.json (Order.OrderStatusContent.adminAssistedLabel = "Order placed by an administrator"). */} + diff --git a/src/content/docs/dropins/order/dictionary.mdx b/src/content/docs/dropins/order/dictionary.mdx index 64a0a9975..01a2df7eb 100644 --- a/src/content/docs/dropins/order/dictionary.mdx +++ b/src/content/docs/dropins/order/dictionary.mdx @@ -244,6 +244,7 @@ Below are the default English (`en_US`) strings provided by the **Order** drop-i }, "OrderStatusContent": { "noInfoTitle": "Check back later for more details.", + "adminAssistedLabel": "Order placed by an administrator", "returnMessage": "The order was placed on {ORDER_CREATE_DATE} and your return process started on {RETURN_CREATE_DATE}", "returnStatus": { "pending": "Pending", diff --git a/src/content/docs/dropins/order/index.mdx b/src/content/docs/dropins/order/index.mdx index 189fa2f51..185a11e70 100644 --- a/src/content/docs/dropins/order/index.mdx +++ b/src/content/docs/dropins/order/index.mdx @@ -3,12 +3,16 @@ title: Order overview description: Learn about the features and functions of the order drop-in component. --- -import { Badge } from '@astrojs/starlight/components'; +import { Aside, Badge } from '@astrojs/starlight/components'; import OptionsTable from '@components/OptionsTable.astro'; import Diagram from '@components/Diagram.astro'; The order drop-in component provides a comprehensive set of tools and containers designed to manage and display order-related data across various pages and scenarios. It simplifies the implementation of order management functionality and supports seamless integration with both customer accounts and guest user workflows. + + ## Architecture The order drop-in component consists of multiple containers that display order details on different pages, such as: @@ -45,3 +49,7 @@ The following table provides an overview of the Adobe Commerce guest user featur | View list of orders on the account | | | View order status | | | View return status | | + +## See also + +- [Seller-assisted buying](/dropins/user-account/containers/seller-assisted-buying/) — extends this drop-in so the `OrderStatus` container labels orders placed by an administrator during an assisted session. diff --git a/src/content/docs/dropins/user-account/containers/index.mdx b/src/content/docs/dropins/user-account/containers/index.mdx index a268d6e2f..d2166ccfa 100644 --- a/src/content/docs/dropins/user-account/containers/index.mdx +++ b/src/content/docs/dropins/user-account/containers/index.mdx @@ -31,6 +31,9 @@ Containers are pre-built UI components that combine functionality, state managem | [CustomerInformation](/dropins/user-account/containers/customer-information/) | Learn about the `CustomerInformation` container. | | [OrdersList](/dropins/user-account/containers/orders-list/) | Learn about the `OrdersList` container. | | [PaymentMethods](/dropins/user-account/containers/payment-methods/) | List stored payment methods in My Account; shoppers confirm removal in a dialog before the vault token is deleted. | +| [Seller-assisted buying](/dropins/user-account/containers/seller-assisted-buying/) | End-to-end overview of seller-assisted buying across Auth, Account, and Order drop-ins. | +| [SellerAssistedBuyingActivity](/dropins/user-account/containers/seller-assisted-buying-activity/) | Show a read-only log of administrator actions taken during seller-assisted buying sessions. | +| [SellerAssistedBuyingSettings](/dropins/user-account/containers/seller-assisted-buying-settings/) | Let customers enable or disable remote shopping assistance for their account. | diff --git a/src/content/docs/dropins/user-account/containers/orders-list.mdx b/src/content/docs/dropins/user-account/containers/orders-list.mdx index 51a1b903e..8fd31f52e 100644 --- a/src/content/docs/dropins/user-account/containers/orders-list.mdx +++ b/src/content/docs/dropins/user-account/containers/orders-list.mdx @@ -78,3 +78,20 @@ export default async function decorate(block) { } } ``` + +## Administrator-assisted orders + +When the seller-assisted buying feature is in use, the `OrdersList` container shows a "Placed by an administrator" label on any order where `adminAssistedOrder > 0`. The label appears automatically in both the minified and full-size views. No configuration is required. + + + ![Order card showing the administrator label](@images/dropins/SAB-OrdersList.png) + + +To customize the label text, override the dictionary key in the account initializer: + +- Minified view: `Account.minifiedView.OrdersList.OrdersListCard.placedByAdministrator` +- Full-size view: `Account.fullSizeView.OrdersList.OrdersListCard.placedByAdministrator` + +For the end-to-end flow, see [Seller-assisted buying](/dropins/user-account/containers/seller-assisted-buying/). + +{/* Verified against adobe-commerce/storefront-account src/components/OrdersListCard/OrdersListCard.tsx: minifiedViewKey = minifiedView ? 'minifiedView' : 'fullSizeView' (line 46) builds Account.${minifiedViewKey}.OrdersList.OrdersListCard.placedByAdministrator (line 54), rendered when adminAssistedOrder > 0 (lines 123-124); src/data/models/order-history-list.ts transforms admin_assisted_order. */} diff --git a/src/content/docs/dropins/user-account/containers/seller-assisted-buying-activity.mdx b/src/content/docs/dropins/user-account/containers/seller-assisted-buying-activity.mdx new file mode 100644 index 000000000..fec60422d --- /dev/null +++ b/src/content/docs/dropins/user-account/containers/seller-assisted-buying-activity.mdx @@ -0,0 +1,61 @@ +--- +title: SellerAssistedBuyingActivity container +description: Learn about the SellerAssistedBuyingActivity container in the User Account drop-in. +sidebar: + label: SellerAssistedBuyingActivity +--- + +import TableWrapper from '@components/TableWrapper.astro'; +import { Aside } from '@astrojs/starlight/components'; +import Diagram from '@components/Diagram.astro'; + +The `SellerAssistedBuyingActivity` container displays a read-only table of administrator actions recorded during seller-assisted buying sessions. The table shows three columns: action, date, and details. Customers can review what an administrator did on their behalf but cannot modify or delete any records. + +This container is part of the seller-assisted buying feature. For the end-to-end flow and Admin setup, see [Seller-assisted buying](/dropins/user-account/containers/seller-assisted-buying/). When remote shopping assistance is disabled at the store level, the container displays a feature-disabled message instead of the table. + + + ![Administrator activity log](@images/dropins/SAB-log.png) + + +## Configuration + + + +| Parameter | Type | Req? | Description | +| --------- | ---- | ---- | ----------- | +| `className` | `string` | No | Custom CSS class applied to the root container element. Merged with the default class. Use to apply brand styles or integrate with a utility CSS framework. | +| `pageSize` | `number` | No | Number of activity items shown per page. Controls both the GraphQL query page size and UI pagination. Defaults to `10`. Use smaller values (5–10) for mobile-optimized views and larger values (15–25) for desktop auditing scenarios. | +| `withWrapper` | `boolean` | No | Controls whether the table is wrapped in the default Card component. Defaults to `false`. Set to `true` when you want the drop-in to provide its own card wrapper. | + + + +## Slots + +This container does not expose any customizable slots. + +## Usage + +The boilerplate already includes the `commerce-seller-assisted-buying-activity` block, which renders this container with `withWrapper: false`. No changes are required to place the activity log on a page. + +To increase the number of rows shown per page, pass `pageSize` to the render call in the block file: + +```js +await accountRenderer.render(SellerAssistedBuyingActivity, { + pageSize: 20, + withWrapper: false, +})(container); +``` + +To wrap the table in the drop-in's default Card component, set `withWrapper: true`: + +```js +await accountRenderer.render(SellerAssistedBuyingActivity, { + withWrapper: true, +})(container); +``` + + + +{/* Verified against @dropins/storefront-account@4.0.0-beta.0 (npm): types/sellerAssistedBuyingActivity.types.d.ts (SellerAssistedBuyingActivityProps: className?, pageSize?, withWrapper? — withWrapper defaults to false per README and package types) and containers/SellerAssistedBuyingActivity/SellerAssistedBuyingActivity.d.ts. Column names (action, date, details) verified against SellerAssistedBuyingActivityTableProps.tableHeaders. */} diff --git a/src/content/docs/dropins/user-account/containers/seller-assisted-buying-settings.mdx b/src/content/docs/dropins/user-account/containers/seller-assisted-buying-settings.mdx new file mode 100644 index 000000000..8d6eb4094 --- /dev/null +++ b/src/content/docs/dropins/user-account/containers/seller-assisted-buying-settings.mdx @@ -0,0 +1,50 @@ +--- +title: SellerAssistedBuyingSettings container +description: Learn about the SellerAssistedBuyingSettings container in the User Account drop-in. +sidebar: + label: SellerAssistedBuyingSettings +--- + +import TableWrapper from '@components/TableWrapper.astro'; +import { Aside } from '@astrojs/starlight/components'; +import Diagram from '@components/Diagram.astro'; + +The `SellerAssistedBuyingSettings` container lets customers manage their remote shopping assistance preference. It shows a checkbox that enables or disables an administrator's ability to access and manage the customer's shopping session. It also renders an optional tooltip, a dismissible warning when assistance is turned off, and a message when the feature is not available at the store level. + +This container is part of the seller-assisted buying feature. For the end-to-end flow and Admin setup, see [Seller-assisted buying](/dropins/user-account/containers/seller-assisted-buying/). + + + ![Remote shopping assistance consent checkbox](@images/dropins/SAB-Settings.png) + + +## Configuration + + + +| Parameter | Type | Req? | Description | +| --------- | ---- | ---- | ----------- | +| `className` | `string` | No | Custom CSS class applied to the root container element. Merged with the default class. Use to apply brand styles or integrate with a utility CSS framework. | + + + +## Slots + +This container does not expose any customizable slots. + +## Usage + +The boilerplate already includes the `commerce-seller-assisted-buying-settings` block, which renders this container with no additional configuration. No changes are required to place the preference control on a page. + +To apply a custom CSS class to the container root, pass `className` to the render call in the block file: + +```js +await accountRenderer.render(SellerAssistedBuyingSettings, { + className: 'my-settings-wrapper', +})(container); +``` + + + +{/* Verified against adobe-commerce/storefront-account src/types/sellerAssistedBuyingSettings.types.ts (SellerAssistedBuyingSettingsProps: className?) and src/containers/SellerAssistedBuyingSettings/SellerAssistedBuyingSettings.tsx. */} diff --git a/src/content/docs/dropins/user-account/containers/seller-assisted-buying.mdx b/src/content/docs/dropins/user-account/containers/seller-assisted-buying.mdx new file mode 100644 index 000000000..6752ab087 --- /dev/null +++ b/src/content/docs/dropins/user-account/containers/seller-assisted-buying.mdx @@ -0,0 +1,64 @@ +--- +title: Seller-assisted buying +description: Learn how seller-assisted buying lets a store administrator shop on a customer's behalf, and where each part is documented across the Auth, Account, and Order drop-ins. +sidebar: + label: Seller-assisted buying +--- + +import { Aside } from '@astrojs/starlight/components'; +import Link from '@components/Link.astro'; +import Term from '@components/Term.astro'; +import Diagram from '@components/Diagram.astro'; + +Seller-assisted buying lets a store administrator log in as a customer and act on their behalf by browsing products, building a cart, and placing orders. During the session, a banner tells the administrator they are browsing as the customer. Afterward, the customer can review every administrator action in their account activity log. + +Seller-assisted buying is not a separate drop-in or package. It extends three drop-ins you already have and adds a session banner to the boilerplate. + + + +## How it works + +When seller-assisted buying is enabled at the store level, an administrator generates a one-time password (OTP) in the Admin. The administrator uses the OTP to sign in as the customer through the standard storefront sign-in flow. The `storefront-auth` drop-in decodes the returned JSON Web Token (JWT) and checks it for an admin identifier. When the token includes an admin identifier, the drop-in sets an `auth_dropin_admin_session` cookie. + +The boilerplate header block reads that cookie on every page load. When the cookie is present, the block renders the session banner. The banner listens to the `authenticated` event and removes itself when the session ends. See [Session banner](#session-banner) for the UI details and CSS classes. + +If remote shopping assistance is disabled at the store level, both the settings block and the activity block display a feature-disabled message rather than their normal UI. + +## Where each part is documented + +Because the feature spans several drop-ins, each piece lives with the drop-in it belongs to: + +- Consent checkbox on the sign-up form — [User Auth — SignUp container](/dropins/user-auth/containers/sign-up/#seller-assisted-buying-consent) and the [`RemoteShoppingAssistanceConsent` slot](/dropins/user-auth/slots/#remoteshoppingassistanceconsent-slot). To relabel the checkbox or change its tooltip text, go to **Stores** > **Settings** > **Configuration** > **Customers** > **Login as Customer** in the Admin. +- Customer preference control (`commerce-seller-assisted-buying-settings`) — [User Account — SellerAssistedBuyingSettings container](/dropins/user-account/containers/seller-assisted-buying-settings/) +- Administrator activity log (`commerce-seller-assisted-buying-activity`) — [User Account — SellerAssistedBuyingActivity container](/dropins/user-account/containers/seller-assisted-buying-activity/) +- Order label in the orders list — [User Account — OrdersList container](/dropins/user-account/containers/orders-list/#administrator-assisted-orders) +- Order label on the order status page — [Order — OrderStatus container](/dropins/order/containers/order-status/#administrator-assisted-orders) +- Functions and data models — [User Account — Functions](/dropins/user-account/functions/#getadminassistanceactions) +- Text and labels — [User Account — Dictionary](/dropins/user-account/dictionary/#seller-assisted-buying-keys) and [Order — Dictionary](/dropins/order/dictionary/) +- CSS classes — [User Account — Styles](/dropins/user-account/styles/) + +## Session banner + + + ![Session banner showing administrator connection status and Close Session button](@images/dropins/SAB-Boilerplate.png) + + +The session banner lives in the boilerplate header block, not in a drop-in. It renders automatically when an admin session is active. You don't need to add any code. The banner shows the customer's name and the website name, and includes a "Close Session" button that calls `revokeCustomerToken()` and redirects to the home page. The CSS and rendering logic ship with the header block (`blocks/header/header.css` and `blocks/header/renderSellerAssistedBuyingBanner.js`). + +Target these classes to restyle the banner: + +```css title="blocks/header/header.css" +/* Adds top padding to page content so the banner does not overlap it */ +body:has(.seller-assisted-buying-banner) {} + +/* Banner strip — rendered at the top of the page during an assisted session */ +.seller-assisted-buying-banner {} +.seller-assisted-buying-banner__message {} +.seller-assisted-buying-banner__close-button {} +``` + +If you change the banner height, update `body:has(.seller-assisted-buying-banner)` at the same time so the page content shifts down by the same amount. + +{/* Verified against adobe-commerce/storefront-auth (main): src/lib/jwtUtils.ts (decodeJwtToken, isAdminToken via positive admin_id), src/api/getCustomerToken/getCustomerToken.ts (sets auth_dropin_admin_session cookie, emits authenticated), src/api/revokeCustomerToken/revokeCustomerToken.ts. Banner verified against hlxsites/aem-boilerplate-commerce (integration branch, PR #1283, merged 2026-06-05): blocks/header/header.js reads the cookie and renders blocks/header/renderSellerAssistedBuyingBanner.js (customer name + website name, Close Session calls revokeCustomerToken then redirects home, removes itself on authenticated event). Block examples verified against integration branch: blocks/commerce-seller-assisted-buying-settings/commerce-seller-assisted-buying-settings.js (renders SellerAssistedBuyingSettings with no extra options) and blocks/commerce-seller-assisted-buying-activity/commerce-seller-assisted-buying-activity.js (renders SellerAssistedBuyingActivity with withWrapper: false). */} diff --git a/src/content/docs/dropins/user-account/dictionary.mdx b/src/content/docs/dropins/user-account/dictionary.mdx index 97019eb58..7bb98eae2 100644 --- a/src/content/docs/dropins/user-account/dictionary.mdx +++ b/src/content/docs/dropins/user-account/dictionary.mdx @@ -208,7 +208,8 @@ Below are the default English (`en_US`) strings provided by the **User Account** "itemsAmount": "items", "carrier": "Carrier:", "returns": "Return(s):", - "orderDate": "Placed on" + "orderDate": "Placed on", + "placedByAdministrator": "Placed by an administrator" }, "OrdersListSelectDate": { "pastSixMonths": "Past 6 months", @@ -274,7 +275,8 @@ Below are the default English (`en_US`) strings provided by the **User Account** "itemsAmount": "items", "carrier": "Carrier:", "returns": "Return(s):", - "orderDate": "Placed on" + "orderDate": "Placed on", + "placedByAdministrator": "Placed by an administrator" }, "OrdersListSelectDate": { "pastSixMonths": "Past 6 months", @@ -346,8 +348,49 @@ Below are the default English (`en_US`) strings provided by the **User Account** "actionCancel": "Cancel", "actionConfirm": "Remove" } + }, + "sellerAssistedBuyingSettings": { + "checkboxLabel": "Enable seller assisted purchasing", + "checkboxTooltip": "This allows merchants to \"see what you see\" and take actions on your behalf in order to provide better assistance.", + "alertMessage": "Seller assisted purchasing is currently disabled. New sessions cannot be started.", + "featureDisabledMessage": "Seller assisted purchasing is unavailable. This feature has been disabled by the store administrator." + }, + "sellerAssistedBuyingActivity": { + "tableHeaders": { + "action": "Action", + "date": "Date", + "details": "Details" + }, + "actionTypes": { + "place_order": "Order Placed", + "add_to_cart": "Added to Cart", + "remove_from_cart": "Removed from Cart", + "remove_cart_item": "Cart Item Removed", + "update_qty": "Quantity Updated", + "apply_coupon": "Coupon Applied", + "remove_coupon": "Coupon Removed", + "update_address": "Address Updated", + "update_payment": "Payment Method Updated", + "update_shipping": "Shipping Method Updated", + "add_product_note": "Product Note Added", + "update_customer_info": "Customer Info Updated", + "save": "Saved" + }, + "emptyStateMessage": "No administrator-assisted actions yet.", + "errorMessage": "Couldn't load administrator-assisted actions. Please try again later.", + "featureDisabledMessage": "Seller assisted activity log is unavailable. This feature has been disabled by the store administrator." } } } ``` +## Seller-assisted buying keys + +The seller-assisted buying feature stores its text under `Account.sellerAssistedBuyingSettings` and `Account.sellerAssistedBuyingActivity`, shown in the default keys above. The `placedByAdministrator` key under `OrdersList.OrdersListCard` (in both `minifiedView` and `fullSizeView`) sets the order label for administrator-placed orders. + + + +{/* Verified against adobe-commerce/storefront-account src/i18n/en_US.json (Account.sellerAssistedBuyingSettings, Account.sellerAssistedBuyingActivity, and OrdersListCard.placedByAdministrator under both minifiedView and fullSizeView). */} + diff --git a/src/content/docs/dropins/user-account/functions.mdx b/src/content/docs/dropins/user-account/functions.mdx index 5dd0652c5..b37b5f249 100644 --- a/src/content/docs/dropins/user-account/functions.mdx +++ b/src/content/docs/dropins/user-account/functions.mdx @@ -24,6 +24,7 @@ The User Account drop-in provides API functions that enable you to programmatica | Function | Description | | --- | --- | | [`createCustomerAddress`](#createcustomeraddress) | Creates an address for an existing customer using the `CustomerAddressesModel` object as an argument. | +| [`getAdminAssistanceActions`](#getadminassistanceactions) | Fetches a paginated list of administrator actions recorded during seller-assisted buying sessions. | | [`getAttributesForm`](#getattributesform) | Calls the `attributesForm` query to retrieve EAV attributes associated with customer and customer address frontend forms. | | [`getCountries`](#getcountries) | Calls the countries query to retrieve a list of countries. | | [`getCustomer`](#getcustomer) | Retrieves the customer information for the logged-in customer. | @@ -32,7 +33,7 @@ The User Account drop-in provides API functions that enable you to programmatica | [`deletePaymentToken`](#deletepaymenttoken) | Removes a stored payment token using the `deletePaymentToken mutation`. | | [`getOrderHistoryList`](#getorderhistorylist) | Retrieves a list of customer orders asynchronously using the customer query. | | [`getRegions`](#getregions) | Calls the country query to retrieve a list of states or provinces for a specific country. | -| [`getStoreConfig`](#getstoreconfig) | Calls the `storeConfig` query to retrieve details about password requirements. | +| [`getStoreConfig`](#getstoreconfig) | Calls the `storeConfig` query to retrieve password requirements and the seller-assisted buying feature flag and consent checkbox settings. | | [`removeCustomerAddress`](#removecustomeraddress) | Removes an address associated with the current customer. | | [`updateCustomer`](#updatecustomer) | Updates the logged-in customer. | | [`updateCustomerAddress`](#updatecustomeraddress) | Updates an address associated with the current customer. | @@ -67,6 +68,51 @@ Does not emit any drop-in events. Returns `string`. +## getAdminAssistanceActions + +The `getAdminAssistanceActions` function fetches a paginated list of administrator actions recorded during seller-assisted buying sessions. The [`SellerAssistedBuyingActivity`](/dropins/user-account/containers/seller-assisted-buying-activity/) container uses this function internally to populate its activity grid. + +```ts +const getAdminAssistanceActions = async ( + pageSize: number, + currentPage: number +): Promise +``` + + + +| Parameter | Type | Req? | Description | +|---|---|---|---| +| `pageSize` | `number` | Yes | Number of items to fetch per page. | +| `currentPage` | `number` | Yes | Page to fetch, starting at `1`. | + + + +### Events + +Does not emit any drop-in events. + +### Returns + +Returns [`AdminAssistanceActions`](#adminassistanceactions) or `null` when the request fails or returns no data. + +### Example + +```js +import { getAdminAssistanceActions } from '@dropins/storefront-account/api.js'; + +const actions = await getAdminAssistanceActions(10, 1); + +if (actions) { + console.log('Total actions:', actions.totalCount); + console.log('Total pages:', actions.pageInfo.totalPages); + + actions.items.forEach((item) => { + console.log(`${item.date}: ${item.action} — ${item.details}`); + }); +} +``` + ## getAttributesForm The `getAttributesForm` function calls the query to retrieve EAV attributes associated with customer and customer address frontend forms. The `formCode` parameter must be one of the following values: `customer_account_create`, `customer_account_edit`, `customer_address_create`, or `customer_address_edit`. @@ -271,7 +317,7 @@ Returns `RegionTransform[] | []`. See [`RegionTransform`](#regiontransform). ## getStoreConfig -The `getStoreConfig` function calls the query to retrieve details about password requirements. +The `getStoreConfig` function calls the query to retrieve details about password requirements. The response also includes the seller-assisted buying fields that control whether the feature is active and customize the consent checkbox shown to customers. ```ts const getStoreConfig = async (): Promise @@ -520,6 +566,55 @@ interface StoreConfigModel { minLength: number; requiredCharacterClasses: number; storeCode: string; + shoppingAssistanceEnabled: boolean; + shoppingAssistanceCheckboxTitle: string; + shoppingAssistanceCheckboxTooltip: string; +} +``` + +The seller-assisted buying fields: + + + +| Field | Type | Description | +| --- | --- | --- | +| `shoppingAssistanceEnabled` | `boolean` | `true` when seller-assisted buying is enabled at the store level. Controlled by the **Enable Extension** setting in the Admin. The seller-assisted buying containers use this value to show or hide feature content. | +| `shoppingAssistanceCheckboxTitle` | `string` | Label for the consent checkbox. Set by the **Title for Login as Customer opt-in checkbox** field in the Admin. Falls back to the dictionary value when not configured. | +| `shoppingAssistanceCheckboxTooltip` | `string` | Tooltip text for the consent checkbox. Set by the **Login as Customer checkbox tooltip** field in the Admin. Falls back to the dictionary value when not configured. | + + + +### AdminAssistanceActions + +The `AdminAssistanceActions` object is returned by the following functions: [`getAdminAssistanceActions`](#getadminassistanceactions). + +```ts +interface AdminAssistanceActions { + totalCount: number; + items: AdminAssistanceAction[]; + pageInfo: AdminAssistanceActionsPageInfo; +} +``` + +### AdminAssistanceAction + +Each item in the `items` array. The `action` field contains one of the action type keys defined for seller-assisted buying. See the [User Account dictionary](/dropins/user-account/dictionary/) for the full list of action type keys and their default labels. + +```ts +interface AdminAssistanceAction { + action: string; + date: string; + details: string; +} +``` + +### AdminAssistanceActionsPageInfo + +```ts +interface AdminAssistanceActionsPageInfo { + currentPage: number; + pageSize: number; + totalPages: number; } ``` diff --git a/src/content/docs/dropins/user-account/index.mdx b/src/content/docs/dropins/user-account/index.mdx index bfb307c41..b7d6380e0 100644 --- a/src/content/docs/dropins/user-account/index.mdx +++ b/src/content/docs/dropins/user-account/index.mdx @@ -5,11 +5,15 @@ sidebar: order: 1 --- -import { Badge } from '@astrojs/starlight/components'; +import { Aside, Badge } from '@astrojs/starlight/components'; import OptionsTable from '@components/OptionsTable.astro'; The user account drop-in component provides account management features in your storefront. + + ## Supported Commerce features The following table provides an overview of the Adobe Commerce features that the user account drop-in component supports: @@ -19,9 +23,13 @@ The following table provides an overview of the Adobe Commerce features that the | Add/remove new address | | | Change email | | | Change password | | -| Login as customer | | +| Login as customer | | | Manage products in wishlist | | | Move products from wishlist to cart | | | Update address | | | View addresses saved during checkout | | | View stored payment methods and remove them after confirmation | | + +## See also + +- [Seller-assisted buying](/dropins/user-account/containers/seller-assisted-buying/) — extends this drop-in with the `SellerAssistedBuyingSettings` and `SellerAssistedBuyingActivity` containers and an administrator order label on the `OrdersList` container. diff --git a/src/content/docs/dropins/user-account/styles.mdx b/src/content/docs/dropins/user-account/styles.mdx index 517b768b0..06897b97d 100644 --- a/src/content/docs/dropins/user-account/styles.mdx +++ b/src/content/docs/dropins/user-account/styles.mdx @@ -174,6 +174,26 @@ The User Account drop-in uses BEM-style class naming. Use the browser DevTools t .account-payment-card__card-number {} .account-payment-card__labels {} .dropin-card__content {} + +/* SellerAssistedBuyingSettings (container root) */ +.account-seller-assisted-buying-settings {} + +/* SellerAssistedBuyingSettingsControl (inner control component) */ +.account-seller-assisted-buying-settings-control {} +.account-seller-assisted-buying-settings-control__checkbox-row {} +.account-seller-assisted-buying-settings-control__info-container {} +.account-seller-assisted-buying-settings-control__info-icon {} +.account-seller-assisted-buying-settings-control__tooltip {} +.account-seller-assisted-buying-settings-control__tooltip-arrow {} + +/* SellerAssistedBuyingActivity (container root) */ +.account-seller-assisted-buying-activity {} + +/* SellerAssistedBuyingActivityTable (inner table component) */ +.account-seller-assisted-buying-activity-table {} +.account-seller-assisted-buying-activity-table__table {} +.account-seller-assisted-buying-activity-table__table-wrapper {} +.account-seller-assisted-buying-activity-table__pagination {} ``` diff --git a/src/content/docs/dropins/user-auth/containers/sign-up.mdx b/src/content/docs/dropins/user-auth/containers/sign-up.mdx index bdd41ebd0..0bf348200 100644 --- a/src/content/docs/dropins/user-auth/containers/sign-up.mdx +++ b/src/content/docs/dropins/user-auth/containers/sign-up.mdx @@ -41,6 +41,14 @@ If a user creates an account when email confirmation is enabled, a different for ![SignUp container](@images/user-auth/sign-up-verify-email.png) +## Seller-assisted buying consent + +When the seller-assisted buying feature is enabled at the store level, the SignUp form shows a remote shopping assistance consent checkbox. The checkbox label and tooltip come from the Admin configuration, and the form submits the consent value with the create-account mutation. Customize this section with the `RemoteShoppingAssistanceConsent` slot. See [User Auth slots](/dropins/user-auth/slots/#remoteshoppingassistanceconsent-slot) for the slot and [Seller-assisted buying](/dropins/user-account/containers/seller-assisted-buying/) for the end-to-end flow. + + + ![Sign-up form with remote shopping assistance consent checkbox](@images/dropins/SAB-SignUp.png) + + ## SignUp configurations The SignUp container provides the following configuration options: @@ -107,7 +115,7 @@ The SignUp container provides the following configuration options: 'slots', 'function', 'No', - 'Defines the slot to pass. The SuccessNotification slot can pass the SuccessNotification container, or other custom component rendered upon successful sign-up, if routeRedirectOnSignIn is not provided. The PrivacyPolicyConsent slot allows passing a custom component to display a static privacy consent message in the sign-up form.', + 'Defines the slot to pass. The SuccessNotification slot can pass the SuccessNotification container, or other custom component rendered upon successful sign-up, if routeRedirectOnSignIn is not provided. The PrivacyPolicyConsent slot allows passing a custom component to display a static privacy consent message in the sign-up form. The RemoteShoppingAssistanceConsent slot customizes the seller-assisted buying consent checkbox, rendered only when that feature is enabled.', ], [ 'routeSignIn', diff --git a/src/content/docs/dropins/user-auth/index.mdx b/src/content/docs/dropins/user-auth/index.mdx index 48b63db7d..53d7c5512 100644 --- a/src/content/docs/dropins/user-auth/index.mdx +++ b/src/content/docs/dropins/user-auth/index.mdx @@ -5,11 +5,15 @@ sidebar: order: 1 --- -import { Badge } from '@astrojs/starlight/components'; +import { Aside, Badge } from '@astrojs/starlight/components'; import OptionsTable from '@components/OptionsTable.astro'; The user auth drop-in component provides user authentication so customers can sign up, log in, and log out of your storefront. + + ## Supported Commerce features The following table provides an overview of the Adobe Commerce features that the user auth drop-in component supports: diff --git a/src/content/docs/dropins/user-auth/slots.mdx b/src/content/docs/dropins/user-auth/slots.mdx index a63fb60cb..187d810f8 100644 --- a/src/content/docs/dropins/user-auth/slots.mdx +++ b/src/content/docs/dropins/user-auth/slots.mdx @@ -27,7 +27,7 @@ Do not use context methods inside other context methods (for example, `appendChi | Container | Slots | |-----------|-------| | [`SignIn`](#signin-slots) | `Title`, `Form`, `Buttons`, `SuccessNotification` | -| [`SignUp`](#signup-slots) | `Title`, `Form`, `Buttons`, `SuccessNotification`, `PrivacyPolicyConsent` | +| [`SignUp`](#signup-slots) | `Title`, `Form`, `Buttons`, `SuccessNotification`, `PrivacyPolicyConsent`, `RemoteShoppingAssistanceConsent` | | [`ResetPassword`](#resetpassword-slots) | `Title`, `Form`, `Buttons` | | [`SuccessNotification`](#successnotification-slots) | `SuccessNotificationActions` | | [`UpdatePassword`](#updatepassword-slots) | `Title`, `Form`, `Buttons`, `SuccessNotification` | @@ -122,6 +122,7 @@ interface SignUpProps { Buttons?: SlotProps; SuccessNotification?: SlotProps; PrivacyPolicyConsent: SlotProps; + RemoteShoppingAssistanceConsent?: SlotProps; }; } ``` @@ -209,6 +210,41 @@ await provider.render(SignUp, { })(block); ``` +### RemoteShoppingAssistanceConsent slot + +The `RemoteShoppingAssistanceConsent` slot lets you customize the remote shopping assistance consent checkbox shown in the `SignUp` form. This slot belongs to the seller-assisted buying feature and renders only when seller-assisted buying is enabled at the store level. When the feature is disabled, the slot does not render. For the end-to-end flow and Admin setup, see [Seller-assisted buying](/dropins/user-account/containers/seller-assisted-buying/). + +#### Example + +```js +import { render as provider } from '@dropins/storefront-auth/render.js'; +import { SignUp } from '@dropins/storefront-auth/containers/SignUp.js'; + +await provider.render(SignUp, { + slots: { + RemoteShoppingAssistanceConsent: (ctx) => { + const wrapper = document.createElement('div'); + wrapper.className = 'custom-consent'; + + const input = document.createElement('input'); + input.type = 'checkbox'; + input.name = 'allowRemoteShoppingAssistance'; + input.value = 'true'; + + const label = document.createElement('label'); + label.append(input, ' I agree to remote shopping assistance'); + + wrapper.appendChild(label); + ctx.appendChild(wrapper); + }, + } +})(block); +``` + + + ## ResetPassword slots The slots for the `ResetPassword` container allow you to customize its appearance and behavior. The slot context (for example, `ResetPasswordSlotContext`) includes properties such as `isLoading`. diff --git a/src/content/docs/merchants/blocks/b2c/index.mdx b/src/content/docs/merchants/blocks/b2c/index.mdx index 1a92731e5..2c924aac7 100644 --- a/src/content/docs/merchants/blocks/b2c/index.mdx +++ b/src/content/docs/merchants/blocks/b2c/index.mdx @@ -31,6 +31,7 @@ If you are new to Commerce blocks, read [Author and developer tasks](/merchants/ | [Commerce Customer Details](/merchants/blocks/commerce-customer-details/) | Shows customer information in order context | Order details page | | [Commerce Account Header](/merchants/blocks/commerce-account-header/) | Displays account navigation and user information | Account section header | | [Commerce Account Sidebar](/merchants/blocks/commerce-account-sidebar/) | Provides account navigation menu | Account section sidebar | +| [Seller-Assisted Buying](/merchants/blocks/seller-assisted-buying/) | Lets administrators shop on a customer's behalf; includes customer preference control and activity log blocks | Customer account settings page, customer account activity page | | **Order Management** | | | | [Commerce Orders List](/merchants/blocks/commerce-orders-list/) | Lists all customer orders with status and details | Order history page | | [Commerce Search Order](/merchants/blocks/commerce-search-order/) | Allows guest order lookup by order number and email | Guest order tracking page | diff --git a/src/content/docs/merchants/blocks/seller-assisted-buying.mdx b/src/content/docs/merchants/blocks/seller-assisted-buying.mdx new file mode 100644 index 000000000..65b5aec0f --- /dev/null +++ b/src/content/docs/merchants/blocks/seller-assisted-buying.mdx @@ -0,0 +1,102 @@ +--- +title: Seller-Assisted Buying +description: Let store administrators sign in as a customer and shop on their behalf. Two blocks support this feature on your customer account pages. +sidebar: + label: Seller-Assisted Buying +--- + +import { Aside, Steps } from '@astrojs/starlight/components'; +import Diagram from '@components/Diagram.astro'; +import TaskSection from '@components/TaskSection.astro'; +import Link from '@components/Link.astro'; + +Seller-assisted buying lets a store administrator sign in as a customer and act on their behalf — browsing products, adding items to a cart, and placing orders. A banner at the top of every page tells the administrator they are browsing as that customer. Afterward, the customer can see every administrator action in their account activity log. + +Two blocks support this feature on the customer account pages: + +- `commerce-seller-assisted-buying-settings` — lets the customer allow or revoke administrator access to their account. +- `commerce-seller-assisted-buying-activity` — shows the customer a history of administrator actions taken during assisted sessions. + +Before using this feature, complete the prerequisite setup in the guide on Experience League: enable the feature in store configuration, grant the Admin user role permission, and ensure the customer has allowed remote shopping assistance either from their account or from the customer's edit page in the Admin. + +## What shoppers see + + + ![Remote shopping assistance consent checkbox](@images/dropins/SAB-Settings.png) + + + + ![Administrator activity log showing actions from a seller-assisted buying session](@images/dropins/SAB-log.png) + + +The session banner appears at the top of every page while an administrator is browsing as a customer. + + + ![Session banner showing administrator connection status and Close Session button](@images/dropins/SAB-Boilerplate.png) + + + + +## Sign in as a customer + +Once you have generated a one-time password (OTP) from the customer's edit page in the Admin: + + + +1. Go to your storefront sign-in page. + +1. Enter the customer's email address and paste the OTP as the password, then sign in. + + The session banner appears at the top of every page. You are now browsing as the customer. + + + + + + + + + +## End a session + + + +1. Click **Close Session** in the banner at the top of the page. + + The session ends and you are redirected to the home page. + + + +The customer can also revoke administrator access at any time from their account settings page using the `commerce-seller-assisted-buying-settings` block. + + + +## Block tables + +Neither block requires any configuration rows. A header-only table is enough to place the block on a page. + +Place `commerce-seller-assisted-buying-settings` on your customer account settings page: + + + + + + + +
commerce-seller-assisted-buying-settings
+ +Place `commerce-seller-assisted-buying-activity` on your customer account activity page: + + + + + + + +
commerce-seller-assisted-buying-activity
+ +## Related resources + +- — full Admin setup and OTP generation steps on Experience League diff --git a/src/content/docs/releases/changelog.mdx b/src/content/docs/releases/changelog.mdx index 20e089f03..a160e6296 100644 --- a/src/content/docs/releases/changelog.mdx +++ b/src/content/docs/releases/changelog.mdx @@ -666,7 +666,7 @@ import Link from '@components/Link.astro'; The Storefront Compatibility Package has been updated with the following enhancements and fixes: - **Login as Customer**: - - Added support for seller-assisted buying through GraphQL using one-time login codes generated from Admin. + - Added support for seller-assisted buying through GraphQL using one-time passwords (OTP) generated from Admin. - Added `admin_assistance_actions` to the `Customer` type and `admin_assisted_order` to the `CustomerOrder` type. - Added `exchangeOtpForCustomerToken` mutation support alongside `generateCustomerToken`. - Added reCAPTCHA validation for `generateCustomerToken` with optional bypass support for `exchangeOtpForCustomerToken`. @@ -716,7 +716,7 @@ import Link from '@components/Link.astro'; > The Storefront Compatibility Package has been updated to include the following changes: - - **Login as Customer**: Fixed a backend popup issue with one-time login code generation for Login as Customer. + - **Login as Customer**: Fixed a backend popup issue with one-time password (OTP) generation for Login as Customer. The Storefront Compatibility Package has been updated to include the following changes: - - **Login as Customer**: A new Login as Customer feature supports seller-assisted buying. Admins can generate a one-time login code from the customer view in **Admin** and use it to authenticate as the customer through GraphQL. The schema adds `admin_assistance_actions` on the `Customer` type to record admin activity and `admin_assisted_order` on the `CustomerOrder` type for orders placed with assistance. The `exchangeOtpForCustomerToken` mutation exchanges the one-time code for a customer token and works alongside `generateCustomerToken`. + - **Login as Customer**: A new Login as Customer feature supports seller-assisted buying. Admins can generate a one-time password (OTP) from the customer view in **Admin** and use it to authenticate as the customer through GraphQL. The schema adds `admin_assistance_actions` on the `Customer` type to record admin activity and `admin_assisted_order` on the `CustomerOrder` type for orders placed with assistance. The `exchangeOtpForCustomerToken` mutation exchanges the OTP for a customer token and works alongside `generateCustomerToken`. - **Wishlist Items**: Fixed inconsistencies in wishlist items and item count across multiple store views within the same website. Wishlist data is now properly synchronized. - **Cart Items**: Fixed cart availability checks for products where "Manage Stock" is disabled. Cart items now correctly return availability status. diff --git a/src/content/docs/setup/configuration/storefront-compatibility/v248.mdx b/src/content/docs/setup/configuration/storefront-compatibility/v248.mdx index 67395a723..0898143e1 100644 --- a/src/content/docs/setup/configuration/storefront-compatibility/v248.mdx +++ b/src/content/docs/setup/configuration/storefront-compatibility/v248.mdx @@ -36,7 +36,7 @@ The Storefront Compatibility Package defines the following queries and mutations - mutation - Authenticates users via an integration token and returns both the customer token and associated customer data. -- mutation - Authenticates admins as customers for seller-assisted buying by exchanging a one-time code and email for a customer token. +- mutation - Authenticates admins as customers for seller-assisted buying by exchanging a one-time password (OTP) and email for a customer token. - mutation - Updates a customer's billing or shipping address based on the provided customer UID. diff --git a/src/content/docs/setup/configuration/storefront-compatibility/v249.mdx b/src/content/docs/setup/configuration/storefront-compatibility/v249.mdx index 728ff70b7..88d4f308c 100644 --- a/src/content/docs/setup/configuration/storefront-compatibility/v249.mdx +++ b/src/content/docs/setup/configuration/storefront-compatibility/v249.mdx @@ -28,7 +28,7 @@ This Storefront Compatibility Package can be installed on Adobe Commerce 2.4.9 w The Storefront Compatibility Package defines the following queries and mutations: -- mutation - Authenticates admins as customers for seller-assisted buying by exchanging a one-time code and email for a customer token. +- mutation - Authenticates admins as customers for seller-assisted buying by exchanging a one-time password (OTP) and email for a customer token. ## Release information