Context enrichment

The backend already gets your catalog from your e-com backend (ingest). Your app can supplement it with live client-side context so the bot answers without asking — what screen the user is on, what product they're viewing, what's in the cart.

Both methods reuse existing backend frames — there is no backend change required.

Zero-PII contract

The whole payload reaches the model. Never put a buyer's name, email, phone, address, payment data, or any personally-identifying order id in AppContext / CartEvent. Keep it to catalog/UI coordinates and a loggedIn boolean (never a user id).

updateContext(AppContext)

Send on session start and on every screen change. Carries the current screen/route, current product id, viewed category, locale, an auth loggedIn boolean, and arbitrary merchant custom key/values.

React Native

session.updateContext({
  screen: 'ProductDetails',
  currentProductId: 'sku-42',
  category: 'phones',
  locale: 'uk',
  loggedIn: true,
  custom: { promoActive: true },
});

Flutter

session.updateContext(const AppContext(
  screen: 'product',
  route: '/product/42',
  currentProductId: '42',
  category: 'laptops',
  locale: 'uk',
  custom: {'promo': 'summer'}, // arbitrary non-PII signals
));

The latest context is retained and re-sent automatically after a reconnect or resume, so the bot stays oriented across a backgrounding round-trip.

sendCartEvent(...)

Send a cart snapshot on start, then deltas (add / remove / quantity change), so the bot knows what's in the cart without a round-trip.

React Native

// Snapshot on start:
session.sendCartEvent({
  type: 'snapshot',
  currency: 'UAH',
  items: [{ productId: 'sku-42', quantity: 1, price: 14999 }],
});

// Deltas afterward:
session.sendCartEvent({ type: 'add', items: [{ productId: 'sku-7', quantity: 2 }] });

Flutter

session.sendCartEvent(const CartEvent(
  type: CartEventType.added,
  items: [CartLineItem(productId: '42', quantity: 1, price: 15000, currency: 'UAH')],
));

price here is a catalog price, not order/payment data — it stays within the zero-PII contract.

What this maps to on the wire

SDK call	Wire frame
updateContext(...)	{ "type": "client_context", "page_context": {…}, "discovered_urls": [...] }
sendCartEvent(...)	{ "type": "cart_event", … }
(registered handlers)	declared in { "type": "hello", "capabilities": { … } }

See Wire protocol §10 for the frame details.