Visitors
A visitor’s identity on your site, under their consent. Create one with createVisitors.
Extends
Section titled “Extends”Properties
Section titled “Properties”consent
Section titled “consent”
readonlyconsent:ConsentState|null
The consent state from the last answer, or null before one and after the device has been forgotten.
Inherited from
Section titled “Inherited from”
readonlyready:Promise<void>
Resolves once a token kept from an earlier visit has been read into memory. refresh waits for it, so you rarely need it.
readonlytoken:string|null
The current token, or null before the first answer and after the device has been forgotten.
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”adopt()
Section titled “adopt()”adopt(
session):Promise<void>
Takes over a token and consent state that another part of ebitex just issued for this visitor, for example the response to a
form submission, so the whole page shares one visitor. The same rules apply as for refresh: the token is kept on the
device only while consent.recognition is 'granted' and the token is a recognition token, and removed otherwise. Pass
consent: null when the response said nothing about consent; that is treated as not granted. Nothing is sent to ebitex.
Parameters
Section titled “Parameters”session
Section titled “session”consent
Section titled “consent”ConsentState | null
visitor
Section titled “visitor”string
Returns
Section titled “Returns”Promise<void>
consentSignals()
Section titled “consentSignals()”consentSignals():
ConsentSignals
The consent signals this object sends with every request right now: your consent tool’s answer, and the browser’s Global Privacy Control and Do Not Track settings. For code that talks to ebitex on this visitor’s behalf (a form, for example) and must send the same signals.
Returns
Section titled “Returns”event()
Section titled “event()”Call Signature
Section titled “Call Signature”event(
input):Promise<EventResult>
Records a behavioural event for the person this device is recognised as, for example event({ kind: 'content.viewed', subject: { categories } }). Mirrors
POST /audience/delivery/v1/event. An event is not an interaction: it appears on nobody’s timeline and is kept only briefly; audiences count it. Pass an array to send several at once
(they are sent in requests of at most 20). Nothing is stored for an anonymous visitor, and the result says why: that is not an error. Rejects with a VisitorsApiError for a
request that is wrong (an unregistered kind, a category that is not an id, too many categories).
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<EventResult>
Call Signature
Section titled “Call Signature”event(
inputs):Promise<EventResult[]>
Parameters
Section titled “Parameters”inputs
Section titled “inputs”readonly EventInput[]
Returns
Section titled “Returns”Promise<EventResult[]>
forget()
Section titled “forget()”forget():
Promise<string|null>
Forgets this device. The token stops working for good, what that device unlocked is ended (a link to a person, a
connected contact, an emailed-link verification), and the token is removed from memory and storage. Resolves with
the organization’s own wording to show the visitor, or null if there was nothing to forget. Forgetting a device
does not erase the person; that is a separate action by the organization.
If the request fails the token is kept and the promise rejects, so the visitor can try again.
Returns
Section titled “Returns”Promise<string | null>
interaction()
Section titled “interaction()”interaction(
name,properties?,options?):Promise<InteractionResult>
Records something the visitor did, on their timeline in Audience, for example interaction('pricing-viewed', { buyerType: 'agency' }).
It is not a page-view tracker (an interaction is a meaningful fact about a person; high-volume behaviour such as page views is an event, see Visitors.event). An interaction is stored only when this device is recognised and already linked to a person; for
an anonymous visitor nothing is stored and the result says why (it is not an error). name is lower-case words joined by
hyphens, and properties may hold only visit properties your organization has declared, typed as declared. Each device may record
at most 200 interactions in any 24 hours. Rejects with a VisitorsApiError for a bad name or an undeclared or mistyped property
(its errors member says which) and when the daily cap is reached (interaction_cap_reached).
Parameters
Section titled “Parameters”string
properties?
Section titled “properties?”Record<string, unknown>
options?
Section titled “options?”Returns
Section titled “Returns”Promise<InteractionResult>
pageViewed()
Section titled “pageViewed()”pageViewed(
page):Promise<EventResult>
Records that the visitor viewed a page in these categories: event({ kind: 'content.viewed', subject: { categories } }) with an id of its own, so a retry is safe. A single-page app calls it
on each route change; a page with the drop-in script can ask for it on load instead (see data-ebitex-page-views). With no categories nothing is sent.
Parameters
Section titled “Parameters”categories
Section titled “categories”readonly string[]
eventId?
Section titled “eventId?”string
seconds?
Section titled “seconds?”number
Returns
Section titled “Returns”Promise<EventResult>
refresh()
Section titled “refresh()”refresh():
Promise<VisitorSession>
Asks ebitex for the token to use now and the consent state, sending the stored token if there is one. Call it when the page loads, and again whenever your consent tool’s answer changes (or use setConsent). It stores nothing about the visitor; the token is kept on their device only while recognition is granted.
Returns
Section titled “Returns”Promise<VisitorSession>
setConsent()
Section titled “setConsent()”setConsent(
options):Promise<VisitorSession>
Replaces the consent signals, for your consent tool’s callback, and asks again. A cmp of 'denied' is a
withdrawal: the token is dropped from memory and from storage at once, before the network call returns.
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”Promise<VisitorSession>
subscribe()
Section titled “subscribe()”subscribe(
listener): () =>void
Calls listener whenever the token or consent state changes. Returns a function that stops listening.
Parameters
Section titled “Parameters”listener
Section titled “listener”(snapshot) => void
Returns
Section titled “Returns”() => void