Identification & Personalization

Tell HowdyGo who is viewing a demo and replace personalization tokens with values from your app. Install the SDK before calling these methods. To capture visitor information from forms, CRM cookies, or analytics tools automatically, configure the Tracking Script.

identify(userInfo)

Send the current viewer’s identity to every registered HowdyGo demo on the page. The SDK stores it in the browser and supplies it to demos that load later.

howdygo.identify({
  externalUserId: "customer-123",
  email: "jane@example.com",
  name: "Jane Smith",
  company: "Acme Corp",
  phone: "+1234567890",
  traits: { plan: "enterprise", campaign: "autumn-launch" },
  replacements: [
    { token: "welcomeName", value: "Jane" },
    { token: "accountName", value: "Acme Corp" },
  ],
});

All fields are optional:

externalUserId and email are independent. You can identify a signed-in user before you know their email, then add the email later:

howdygo.identify({ externalUserId: "customer-123" });
howdygo.identify({ email: "jane@example.com" });

Updating a viewer’s profile

For the same viewer, identify() preserves fields you omit or set to undefined. Traits merge by key; a supplied replacements array replaces the stored array rather than merging it.

howdygo.identify({
  externalUserId: "customer-123",
  email: "jane@example.com",
  name: "Jane",
  traits: { plan: "pro", campaign: "autumn-launch" },
});
 
// Keeps the IDs and campaign while updating the name and plan.
howdygo.identify({
  name: "Jane Smith",
  traits: { plan: "enterprise" },
});

An empty string is an explicit value, so name: "" clears the stored name. Omitting the field preserves it.

When an existing external user ID changes, the SDK starts a fresh stored profile. A change to a known email also starts a fresh profile unless the call includes the same external user ID. To update the email for the same person, send both fields:

howdygo.identify({
  externalUserId: "customer-123",
  email: "jane.smith@example.com",
});

Learning the first email or external ID preserves the profile information already collected. These profile updates do not start a new demo playback session.

How identity sources are combined

Inside a demo, each field uses the highest-priority available value:

1. Identity supplied by the SDK, with top-level fields taking precedence over traits in the same message.
2. The latest value submitted through a native HowdyGo lead capture form.
3. Personalization token values.
4. Query parameters on the demo URL.

This order is independent of which message arrives first. A later personalization call or demo form does not overwrite an SDK-supplied email, name, phone, or company. A partial SDK update overrides only the fields it supplies.

For externalUserId, use the top-level SDK field or an externalUserId query parameter on the demo URL. The SDK value takes precedence. Traits, personalization tokens, and native form fields cannot set this ID.

Website form capture is handled by the Tracking Script before identity reaches the demo. It can add a missing email and replace an earlier form-captured email, while preserving an email explicitly supplied by your app. Read more about automatic capture and manual identity.

Identity in analytics and integrations

An email is still required to create an Identified Viewer record. Supplying only externalUserId does not create an email-based viewer or CRM contact.

Identity supplied during playback is used by subsequent demo events. Calling identify() alone does not create a demo event or replay earlier events.

Custom event callbacks expose the resolved email as top-level payload.email when viewer identification is enabled. External IDs are not added to the parent-page event payload, GA4 bridge properties, CRM payloads, or webhooks. See the custom event reference for the callback shape.

With a key installed, website identification also works on pages without a demo. That standalone identification does not create a demo viewing session.

personalize(replacements)

Supply token values without calling identify(). Use the token name without braces; for example, welcomeName supplies the value for {{welcomeName}}. See Personalization for adding tokens in the editor.

howdygo.personalize([
  { token: "welcomeName", value: "Jane" },
  { token: "accountName", value: "Acme Corp" },
]);

To identify and personalize in one call, pass the same array as replacements in identify(). Its stored replacements are sent with the identity to demos that register later. A separate personalize() call sends values to demos without updating the SDK’s stored identity.

Tokens named email, name, company, or phone can also provide fallback viewer identity inside the demo, subject to the source priority above. Use descriptive token names such as welcomeName when the text is only for display.

Listening for demo events

Use the custom event listener for session starts, step views, engagement, CTA clicks, and completion. These analytics events arrive as howdygo-demo-event messages on window.

The SDK’s on() and off() methods handle SDK events, such as a newly registered demo:

function onDemoRegistered({ id }) {
  console.log("Demo registered:", id);
}
 
howdygo.on("demo-registered", onDemoRegistered);
 
// Remove this handler when your page no longer needs it.
// howdygo.off("demo-registered", onDemoRegistered);

Advanced methods

Call methods that return values after the SDK has initialized, rather than while the loading snippet is queuing calls.

Clearing stored identity does not stop future capture or clear values already held by an open demo. Opt-out controls SDK storage and automatic tracking; your app should also stop manual identify() calls while the visitor is opted out. Playback and personalization remain available.

Your organization’s Data & privacy controls also apply to viewer identification and analytics.