Widget attributes reference

The script tag

<script
  src="https://cdn.yokaify.com/widget.js"
  data-site-key="YOUR_SITE_KEY"
  async
></script>

Core attributes

Attribute	Required	Description
data-site-key	Yes	Your site's public key from the dashboard. Public by design — security comes from allowed origins, not key secrecy.
data-position	No	Where the widget sits: auto (default — automatically picks a free corner if another chat button is already there), bottom_right, or bottom_left. Overrides the dashboard Appearance setting.
data-api-base	No	Override the API endpoint. Only needed for unusual proxy setups.

Identity attributes (data-yk-*)

Use these when your site knows who the visitor is (logged-in customers). They enable verified features — most importantly order lookup — and better continuity for returning visitors.

Attribute	Description
data-yk-email	The visitor's email address, if you're comfortable passing it directly.
data-yk-email-hash	A hash of the email — lets Yokaify match a customer without receiving the raw address.
data-yk-user-ref	Your internal user reference/ID for the visitor.
data-yk-user-hash	An HMAC signature of the user reference, generated server-side with your signing secret. This is what makes an identity verified.
data-yk-attributes	Additional context attributes for the visitor.

Cart context

On ecommerce platforms the widget reads standard cart signals (item counts, product/variant identifiers, prices) from the page to inform assists — e.g. recognizing an idle cart worth rescuing. On Shopify this works out of the box; custom storefronts can expose the same data through their markup.

Behavior

• The script is async and boots off the critical path.
• SPA route changes are detected automatically (History API patch) — see React/Next.js install.
• Bot traffic is filtered before it consumes AI quota.
• Load the snippet once per page; duplicates try to mount twice.