JavaScript methods
Reference for window.GeoEngage: read the visitor's location, track events and conversions, identify visitors and set attributes.
Every method lives on window.GeoEngage, and every one on this page can be called as soon as the tag has run, except getLocation and getAttributes: ask those inside onReady. See Calling the API.
Location
getLocation
GeoEngage.getLocation(): Location | null
The visitor's location, looked up from their IP address and cached in their browser for an hour. null until the first lookup has finished, so ask for it inside onReady, where it never is.
GeoEngage.onReady((ge) => {
if (ge.getLocation().country_code === 'DE') {
document.querySelector('#delivery-note').textContent = 'Free delivery across Germany';
}
});
A visitor in São Paulo:
{
"continent": "South America",
"continent_code": "SA",
"country": "Brazil",
"country_code": "BR",
"region": "SP",
"region_name": "São Paulo",
"city": "São Paulo",
"zip": "01000-000",
"lat": -23.5475,
"lon": -46.6361,
"timezone": "America/Sao_Paulo",
"ip": "198.51.100.23",
"source": "cloudfront"
}
- Compare
country_code, the two-letter ISO code. country is the country's name when that's known, and the code otherwise.
- A field the lookup couldn't determine is left out, rather than sent empty.
- A visitor who can't be placed at all gets
{ "source": "unknown", "timezone": "…" }, with the timezone from their browser.
Tracking
trackEvent
GeoEngage.trackEvent(name: string, properties?: object): void
Records a custom event, for things the widget can't see by itself: a video played, a wizard step completed, a filter applied.
GeoEngage.trackEvent('video_played', { videoid: 'intro', seconds: 42 });
Events are grouped by name, so keep names short and stable: signup_started, not Signup started on the pricing page. Put the detail in properties instead. Any key is fine, including name or page. Use lowercase names: they are stored lowercase, so videoId reads back as videoid. A call without a name, or with one longer than 100 characters, is ignored.
Custom Events in the dashboard lists each name with its events per day, the share of visits that sent it, and when it last arrived. Open one to see how often each property value came up, and which countries and devices send it. Custom events never count as conversions: use trackConversion with a goal for that.
trackConversion
GeoEngage.trackConversion(name: string, value?: number, metadata?: object): void
Reports a conversion that only your code knows about: an order that went through, a signup your server accepted. Call it where the conversion actually happens, such as your order confirmation page.
GeoEngage.trackConversion('purchase', 99.0, {
orderid: 'ORD-12345',
currency: 'USD',
});
Reports count a conversion only when a goal claims it: create a Conversion from code or Revenue goal in Goals with the same name. The goal counts every call on record with that name, including calls made before you created it. A Revenue goal also adds up value. The other goal types — page visit, element click and form submit — need no code at all. See Goals and conversions.
A name is recorded once per page view: if your confirmation page calls trackConversion('purchase', ...) twice, the first call is kept and the second is ignored. In a single-page app each route change is a new page view.
metadata is kept with the conversion and shown on the goal's own page under Goals, grouped by value. Use lowercase names: they are stored lowercase, so orderId reads back as orderid. Describe the conversion rather than the person — a plan or a currency, not an email address.
Visitors
identify
GeoEngage.identify(email: string): void
Ties the current visitor to an email address. Call it when someone signs in or signs up. Every event recorded afterwards carries the email, until clearIdentity() removes it.
GeoEngage.identify('jane@example.com');
clearIdentity
GeoEngage.clearIdentity(): void
Forgets the email set by identify. Call it when someone signs out.
setAttributes
GeoEngage.setAttributes(attributes: object): object
Stores what your own systems know about the visitor — their plan, their company size, whether they're already a customer — so rules can target it with the Visitor Attribute condition. Returns all of the visitor's attributes.
GeoEngage.setAttributes({ plan: 'pro', seats: 12 });
- Calls merge. A later
setAttributes({ seats: 20 }) changes seats and keeps plan.
- Attributes are kept in the visitor's browser, so a value set inside your app is still there when they visit your pricing page.
- Setting an attribute doesn't re-run the rules on the current page. It takes effect from the next page view or route change, so set attributes as early as you can.
getAttributes
GeoEngage.getAttributes(): object
The attributes stored for this visitor.
clearAttributes
GeoEngage.clearAttributes(): void
Removes every stored attribute, for example when someone signs out.
Configuration
GeoEngage.configure(options: { excludeSelectors?, customSelectors?, tracking? }): void
Changes the tracking settings for the current page, on top of those from Tracking Config in the dashboard. Each option you pass replaces the current value, so pass the complete list.
GeoEngage.configure({
excludeSelectors: ['.account-menu', '[data-private]'],
customSelectors: [{ selector: '.checkout-button', name: 'Checkout' }],
});
| Option | What it does |
|---|
excludeSelectors | Elements the click tracker ignores. |
customSelectors | Extra elements to track as calls to action, as { selector, name }. |
tracking | Other overrides, such as autoTrack: { clicks, forms, scroll, links }. |
notifyRouteChange
GeoEngage.notifyRouteChange(): void
Tells the widget the page changed without a full reload: it removes the current actions, checks your rules again and records a page view. Only needed for a router that doesn't use the History API; see Single-page apps. A call made before the widget is ready does nothing, because its first page view is of the page the visitor is on by then.
Consent and events
grantConsent(), revokeConsent() and hasConsent() are covered in Consent mode.onReady(), onAction(), onEvent() and onExitIntent() are covered in Widget events.