Personalization

How it works

You hand the SDK a free-form JSON object, the additional context, where you configure it. It travels with every suggestion request, and the suggestions that come back are conditioned on it. For a coffee ordering flow, one round looks like this:

1. The user types "Iced latte with", and AI Autocomplete suggests the next field to fill. Here, that is milk.
2. Your app has already sent the customer's saved preference, milk: "oat milk", as part of the additional context.
3. The options for milk arrive with oat milk listed first. A first-time visitor with no context sees the default order instead.
4. The user picks, and the next field is suggested the same way. Context shapes which parameters and options are offered; it never fills anything in on the user's behalf.

What to send

The object is yours to shape. Send whatever your app knows that a good barista, sales assistant, or support agent would want to know about this person before they finish typing.

• Values for your product's own fields carry the most weight. A key named after a field (size, milk, destination) whose value is one of that field's options is listed first whenever the field is suggested.
• A profile and preferences: tier, home store, dietary restrictions, default settings, the workspace or project that is open.
• Recent activity: the last few orders, searches, or documents. Keep a short rolling window rather than the full history.
• Nest as deeply as you like. Any JSON value is accepted, and the shape is never checked against a schema.
• Send nothing when there is nothing to add. An empty object behaves the same as no context at all.

{
  "tier": "gold",
  "home_store": "Gangnam Station",
  "allergies": ["peanut"],
  "preferences": { "milk": "oat milk", "size": "grande" },
  "favorites": ["iced americano", "cold brew"],
  "recent_orders": [
    { "drink": "iced caramel macchiato", "size": "grande", "at": "2026-08-18" }
  ]
}

Step 1: Pass the context

Hand the object to the SDK once, where you configure it. From then on it rides along with every suggestion request the SDK makes; there is nothing to attach per keystroke.

import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-vanilla";

// Whatever your app already knows about this user. Keys named after your
// product's fields ("milk", "size") carry the most weight.
const context = {
  tier: customer.tier,
  home_store: customer.homeStore,
  allergies: customer.allergies,
  preferences: { milk: customer.defaultMilk, size: customer.defaultSize },
  favorites: customer.favorites,
};

// The option is the same in every render mode: "full", "dropdown", "headless".
const ac = new AIAutocomplete(container, {
  apiConfig: { apiKey: "pk_v1_your_public_key" },
  additionalContext: context,
  onSubmit: handleSubmit,
});

Step 2: Keep it current

Context can change while the widget is on screen: the user places an order, switches workspace, or signs in. Replace the object and the next request carries the new value.

• A change is picked up by the next suggestion request. Replacing the context never fires a request of its own.
• The new object replaces the old one; it is not merged. Spread the parts you want to keep.
• Context is kept across a submit or reset, so a returning customer's profile does not need to be set again for their next query.

const recentOrders: Order[] = [];

function refreshContext() {
  // update() replaces the object; spread the profile to keep it.
  ac.update({
    additionalContext: {
      ...context,
      // A rolling window keeps the object under the size cap as the session grows.
      recent_orders: recentOrders.slice(-10).map((o) => ({ drink: o.drink, size: o.size })),
    },
  });
}

ac.on("submit", (result) => {
  placeOrder(result);
  recentOrders.push(toOrder(result));
  // The next query is suggested with this order in its context.
  refreshContext();
});

Size limit

Context is capped at 2000 bytes, measured on the compacted JSON (whitespace does not count). That is roughly a full profile plus a couple dozen history entries.

• Anything past the cap is truncated with a trailing "…" rather than rejected. Nothing errors, but the tail is silently lost.
• Put the most useful keys first: field values and preferences before history.
• Non-ASCII text costs more than one byte per character (three for most Korean or Japanese text), so such a profile reaches the cap sooner.
• For history, keep a rolling window (the last ten orders, not every order) so the object stays under the cap as the session grows.

Privacy and safety

• Context is treated strictly as data. Instructions, role changes, or prompt-like text inside it are ignored.
• Context values are never written into the query on the user's behalf. They only steer which options are offered, and in what order.
• Send only what suggestions can benefit from. Names, emails, phone numbers, and account identifiers add nothing to the ranking, so leave them out.
• PII masking of completed parameters does not extend to context. Masking hides what the user picked; it does not filter what you put in the context object.
• Context travels only with suggestion requests. It is not attached to telemetry, and it is not remembered between requests.

Related

Personalization ranks the options AI Autocomplete already offers. To serve a field's options from your own data entirely (a customer list, live inventory), see Field Injection.