Geofencing Functions
Functions to watch geographic zones (geofences) from your website and react when the user enters, stays in, or leaves one.
A zone is a circle on the map: a centre point (latitude and longitude) and a radius in metres. Once a zone is registered, the app keeps watching it in the background, even when the app is closed. When the user crosses into a zone, stays inside it for a while, or leaves it, the app can:
show a local notification, for example "You're near our Downtown store, show this screen for 10% off", which can open a page of your website when tapped, and
call your webhook, so your backend knows the user arrived or left, for example to check them in, log a visit, or start a delivery.
Typical uses are store-visit offers, attendance and check-in at an office or event, and arrival alerts for pickups and deliveries.
You'll need to import the javascript file in your website before starting from this link.
Platform support: Android and iOS. Every function works on both platforms unless a platform note says otherwise.
openLocationSettingsis iOS only.
Enable it first: Geofencing must be turned on for your app in the WebToNative dashboard. If it is off, the functions get no reply and their promises never settle.
How Geofencing Works
Zone sources (modes)
In the WebToNative dashboard you choose where the app gets its zones from. The mode decides which functions you can use from your website.
Dashboard
The zones you add in the WebToNative dashboard. Every user gets the same zones.
The dashboard
API
Your own endpoint, which the app calls to download the zones. Use it to send different zones to different users.
The dashboard
JS Bridge
Your website, using addZone. Use it when the zones depend on what the user does on your site.
Your website, with setWebhook
In Dashboard and API mode the zones and webhook are managed for you, so the functions that change them reply { status: "not_allowed" }. See Which functions work in which mode.
Triggers
Each zone can fire on three triggers. For each trigger you choose whether to call the webhook, show a notification, or both.
enter
The user crosses into the zone.
dwell
The user has stayed inside the zone for dwellMinutes minutes.
exit
The user leaves the zone.
Location permission
Geofencing only works when the app may use location all the time ("Allow all the time" on Android, "Always" on iOS), because zones are checked in the background. Asking only for "While using the app" is not enough. requestPermission takes the user through the right steps.
Where the API mode gets zones
In API mode, set your endpoint in the dashboard. The app calls it on launch and when you call refreshZones:
GETorPOST(as set in the dashboard), with the headers you set there. No request body is sent.You can put these variables in the URL or header values, and the app fills them in:
{device.platform}(androidorios),{device.appVersion},{device.locale},{device.lat},{device.lng}(last known location, when available).The request times out after 10 seconds.
Your endpoint must reply with a JSON object holding a zones array. Each zone uses the same shape as addZone. ttl (optional) is how many seconds the app may reuse these zones before calling again; the default is 600.
If the call fails, the app keeps using the last zones it downloaded. A zone with an error in it is skipped and the others are still used.
How the Functions Reply
Every WTN.Geofencing function except openLocationSettings returns a Promise. A call ends in one of two ways:
Rejected
.catch
The call was invalid (no zone passed, or the page isn't inside a WebToNative app). Nothing was sent.
Resolved
.then
The app replied. Read status for the result: it can still be "error" or "not_allowed".
Errors
A promise rejects only in these cases. The rejection value is a plain string.
Any function is called outside a WebToNative app (e.g. in a desktop browser)
"This function will work in Native App Powered By WebToNative"
Only call these functions inside the app. Use .catch to hide geofencing UI elsewhere.
The Android app was built before this function was added
"<function> is not supported in this app version", e.g. "addGeofenceZone is not supported in this app version"
Rebuild the app from the WebToNative dashboard and update it on the device.
addZone() is called without zone
"zone is required"
Pass the zone inside an object: addZone({ zone: { ... } }).
Request Permission
Asks the user for "all the time" location access, which geofencing needs. Call it from a button such as "Get offers near our stores", so the user knows why you are asking.
What the user sees:
If the permission is already granted, nothing is shown and the reply comes at once.
Otherwise the app first shows its own explanation screen, with the title, message and buttons you set in the dashboard. If the user taps Not now, the reply comes at once with the current status.
If the user taps Allow location:
Android: the system asks for location, then for "Allow all the time" in a second dialog. When access is granted, the app also asks to be excluded from battery optimization, so zones keep working in the background. If you turned it on in the dashboard, notification permission is asked first.
iOS: the first system dialog only offers "While using the app". After that, the app opens its page in Settings so the user can choose Always. If the user had already denied location, Settings opens directly.
The reply waits for the user's answer, so it can take a while.
Response:
isAlways
Boolean
iOS only. true when the user chose Always. false means only "While using the app", and zones are not watched.
Example responses:
Notes:
On iOS,
status: "granted"also covers "While using the app". Always checkisAlwaystoo, as in the example. On Android,grantedalready means "Allow all the time", andisAlwaysis not sent.After the permission is granted, call
refreshZones()so zones you added before it are registered. Android does this on its own, but iOS doesn't.
Get Permission Status
Reads the location permission without showing anything. Use it on page load to decide whether to show your "Turn on nearby offers" button.
Response: same keys as Request Permission: status, and isAlways on iOS.
Permission status values
granted
Location is allowed. On Android this means "Allow all the time". On iOS check isAlways.
denied
Location is not allowed.
restricted
Blocked for good ("Don't ask again" on Android) or by a system policy on iOS. The user must change it in Settings.
not_determined
Not asked yet. On Android, also when location is allowed only while using the app and "all the time" hasn't been asked yet. Only getPermissionStatus and start reply with it.
Open Location Settings
iOS only. Opens the app's page in iOS Settings, where the user can change location access to Always. iOS can't open the Location setting itself, so tell the user to tap Location → Always.
It returns nothing and there is no reply. Call getPermissionStatus again when the user comes back to the app. On Android it does nothing; use requestPermission instead.
Start
JS Bridge mode only. Starts watching the zones you added with addZone, and replies with the location permission.
What it does on each platform:
Android: never shows a permission dialog. If permission is granted, it registers the saved zones again; if not, it only replies with the status.
iOS: asks for Always location access with the system dialog when needed, without the explanation screen. If access is "While using the app" or denied, it opens the app's page in Settings.
Response:
isAlways
Boolean
iOS only. true when location is allowed Always.
Notes:
Zones are saved on the device and the app watches them again on every launch, so you don't need
starton every page. Calling it once after sign-in, or when your geofencing page opens, is enough.
Zones
The zone object
addZone takes one zone. The same shape is used by the API mode endpoint and returned by getActiveZones.
Zone fields:
_id
String
Yes
Unique id of the zone. Adding a zone with an id that already exists replaces that zone. id is also accepted.
name
String
No
Shown as the notification title on iOS when title is empty, and sent to your webhook.
enabled
Boolean
No
false rejects the zone (status: "error"). Leave it out or pass true.
locationDetails.latitude
Number
Yes
Latitude of the centre.
locationDetails.longitude
Number
Yes
Longitude of the centre.
locationDetails.radius
Number
No
Radius in metres, from 100 to 5000. Default 100. Values outside the range are changed to the nearest limit.
triggers
Object
No
Holds enter, dwell and exit. Each is optional. A zone with no triggers is saved but never fires.
Trigger fields (inside enter, dwell or exit):
active
Boolean
true
false turns this trigger off.
sendPushNotification
Boolean
false
Shows a local notification when the trigger fires. Needs pushNotificationConfig.
pushNotificationConfig.title
String
Notification title.
pushNotificationConfig.body
String
Notification text.
pushNotificationConfig.deepLinkUrl
String
Page opened in the app when the user taps the notification. Leave it out to just open the app.
cooldown
Number
0
Seconds to wait before this trigger can fire again for this zone. 0 fires every time. Covers both the webhook and the notification.
dwellMinutes
Number
1
dwell only. Minutes the user must stay inside before dwell fires.
Add Zone
JS Bridge mode only. Adds one zone and starts watching it. If a zone with the same _id exists, it is replaced.
Response:
status
String
The result. See the values below.
zoneId
String
The zone's id. Missing on Android when the zone was invalid.
status values:
added
New zone saved and watched.
updated
A zone with this id already existed and was replaced.
error
Either the zone is invalid (missing _id, latitude or longitude, or enabled: false) and nothing was saved, or the zone was saved but can't be watched yet because location "all the time" isn't allowed. In the second case, call refreshZones() after the permission is granted.
not_allowed
Your app uses Dashboard or API mode.
Add several zones one after another. Each addZone call must finish before the next one starts (see Notes):
Remove Zone
JS Bridge mode only. Stops watching one zone and deletes it. Pass the zone's id as id.
status values:
removed
The zone was removed.
not_found
No zone has this id.
error
id was missing or empty, or the zone couldn't be removed.
not_allowed
Your app uses Dashboard or API mode.
Get Active Zones
Returns the zones the app is watching, in every mode. Use it to show the user which places they get alerts for, or to check what your API returned.
Response:
Notes:
Zones come back as the app uses them:
radiusis within 100–5000, triggers withactive: falseare left out, anddwellMinutesis a whole number.iOS lists only the zones registered with the system right now. Android lists every saved zone, including ones not watched yet because permission is missing. When you have more zones than the limit, both list only the nearest ones being watched.
Clear All Zones
JS Bridge mode only. Stops watching every zone and deletes them all. Use it when the user signs out. The webhook is kept; call removeWebhook to remove it too.
Refresh Zones
Registers the zones again, in every mode. In API mode it also downloads them from your endpoint right away, even if the ttl hasn't passed. Call it after your backend changes a user's zones.
What it does in each mode:
Dashboard
Registers the zones you added in the dashboard again.
API
Downloads the zones from your endpoint and registers them.
JS Bridge
Registers the zones you added with addZone() again.
status values: refreshed, or error when the zones couldn't be registered (usually because location "all the time" isn't allowed).
Zone limits
The system limits how many zones one app can watch at once: 100 on Android and 20 on iOS.
Webhook
When a trigger with callWebhook: true fires, the app sends a POST request to your webhook URL. Your backend can then react, for example mark the user as checked in.
In Dashboard and API mode, set the webhook in the dashboard. In JS Bridge mode, set it from your website with setWebhook.
Set Webhook
JS Bridge mode only. Sets the URL the app calls when a trigger fires.
Parameters:
url
String
Yes
Your webhook URL. Must start with https://. An http:// URL is saved, but the app never calls it.
headers
Object
No
Headers sent with every webhook request, e.g. an API key. Leave it out to keep the headers from your last call.
status values: set, error (url missing or empty) or not_allowed.
Notes:
Header values must be plain ASCII text. A header with other characters is not sent.
Since nothing in the payload identifies your user in JS Bridge mode, send your user id in a header, as in the example, and call
setWebhookagain after sign-in.
Remove Webhook
JS Bridge mode only. Deletes the webhook. Triggers still show notifications, but no request is sent.
Webhook request
Method
POST, headerContent-Type: application/json, plus your headers.The app tries once and waits up to 3 seconds. A failed request is not sent again, so reply quickly with a
2xxand do slow work afterwards.
Payload:
id
String
Unique id of this event. Use it to ignore duplicates.
event
String
zone.enter, zone.dwell or zone.exit.
timestamp
String
When the trigger fired, in ISO 8601 UTC.
zone
Object
The zone's id, name ("" if none), latitude, longitude and radius.
deviceInfo.id
String
An id for this device and app.
deviceInfo.platform
String
android or ios.
deviceInfo.accuracy_m
Number
Accuracy of the location fix in metres. Can be missing on Android.
Dashboard and API mode only: the webhook settings in the dashboard can add more to the request:
Signing secret: the app adds an
X-W2N-Signatureheader, the HMAC-SHA256 of the raw request body as lowercase hex. Check it to make sure the request came from your app (see the examples below).Custom fields: adds a
customobject. Values can use{user.externalUserId},{user.name},{user.email},{user.phone},{user.meta.<key>},{device.id},{device.platform},{event.type},{event.timestamp},{zone.id}and{zone.name}. A field whose variables can't be filled in is left out.
Receiving the webhook
Notifications on a Trigger
When a trigger has sendPushNotification: true and a pushNotificationConfig, the app shows a local notification. No push service is needed.
Title is
title. On iOS, iftitleis empty, the zone'snameis used, then "Geofence Alert".Text is
body.Tapping it opens
deepLinkUrlin the app, or just opens the app when there is nodeepLinkUrl.On Android, a new notification for the same zone and trigger replaces the previous one.
The user must allow notifications, or nothing is shown. Ask for it with WTN.Permission.request({ permission: "notification" }), or turn on the notification request for the geofencing explanation screen in the dashboard.
Complete Example
A JS Bridge mode page that turns on nearby-store offers for a signed-in user: it checks the permission, asks for it from a button, sets the webhook, and adds the store zones.
When the user signs out, call clearAllZones() and removeWebhook().
Which Functions Work in Which Mode
Notes
Don't call the same function again before the previous call replies. Only the latest call's promise settles; the earlier one never does. For several zones, chain the calls as shown in Add Zone.
If geofencing is turned off in the dashboard, the functions get no reply and their promises never settle.
Switching your app to JS Bridge mode from another mode deletes the old zones once, on the next launch.
On Android, if the device is already inside a zone when you add it,
enterdoesn't fire until the user leaves and comes back.Every function also accepts a
callbackinstead of.then(), e.g.WTN.Geofencing.start({ callback: function (response) { ... } }). Use one or the other.
Last updated