OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Location-Triggered Notifications

Tutorial - Setting up notifications that trigger based on user location.

OneSignal supports sending notifications to devices that have been seen in a specific area, as well as location-triggered (Geofencing) notifications. If using location tracking, please make sure you have Location Tracking Turned on In your App.

We have also partnered with Radar and Plot Projects if you want to integrate with their service.

There are generally 4 ways to target users based on location using OneSignal:

Target By Country

OneSignal automatically tracks a device's country through the IP Address. If you want to convert IP to track by city or designated market area, you can use a 3rd party like MaxMind.


Target By City or Tagged Location

If you collect the user's city or area of interest, you can Add Data Tags to the user based on the provided location.

For example, if your website or mobile app allows users to search by city, area code, zip code, etc. you can tag them with the item they inputed into the text field and use that for segmentation.


Target By Latitude and Longitude

You can setup the app or website to collect latitude and longitude points, then target devices based on a radius around those points. Jump to Mobile Setup or Web Setup.

Mobile Setup

If you have location permissions turned on in your mobile app, OneSignal will also collect those Latitude and Longitude points. See below FAQ How Often OneSignal Updates Location. You can then use Segments or API location Filters to send notifications to users within a provided radius around those points. If you use segments, you can also leverage Automated Messages to send a push when the user enters that segment.

1. Get Location Permissions

To send messages to users by location, make sure you have the location permission set in your app and are prompting for location permissions in your app's code.

Each OneSignal SDK provides a PromptLocation method to help you achieve this.

2. Set up a Segment

Within Segments, create a segment that uses the "Location Radius" filter, and set a distance (in meters) from a set of geo-coordinates (lat,long).

You may skip this step if you pass filters through using the Server REST API.

3. Send to Segment or Filter

Now you can send a message to users in the segment you just created.

You can do this manually via the New Messages Page, automatically via the Server REST API, or automatically via Automated Messages.

Web Setup

Location Tracking on web is only available on HTTPS sites.

1. Determine the user's location

To send messages to users by location, make sure you have the location permission set in your app and are prompting for location permissions in your app's code.

If you need help with this, here is a guide by Mozilla on how to get location permission from a user on your website.

2. Assign location tags

Using the the SendTags method, assign "longitude" and "latitude" tags. For example, you could set "long"="37.160" and "lat"="-117.773".

Here is an example location tracking setup for web.

3. Send to Segment or Filter

Now you can send a message to users in a segment based on these tags.

For example, you could define a segment with tags "long" > 37, "long" < 38, "lat" > -118, "lat" < -117 to create a square target region containing users with location tags in that range.

You can do this manually via the New Messages Page, automatically via the Server REST API, or automatically via the Automated Messages Page.


Target based on a Geofence Trigger

iOS

  1. Follow this guide to set up Geofencing on iOS

  2. When a Geofence is triggered, use the OneSignal postNotification method to send a notification to the device.

Android

  1. Follow this guide to set up Geofencing on Android.

  2. When a Geofence is triggered, use the OneSignal postNotification method to send a notification to the device.


FAQ

How often does the OneSignal SDK update location points?

Depending on the location permissions you set in the app, the location will get updated when the app is open in the Foreground/background or continuously when the app is closed.

For iOS location settings, see the Apple Developer Guide for Choosing the Location Authorization Level

For Android location settings, see the Android Developer Guide on Location Permissions

Starting with android 8, they limit background updates to "a few times every hour", in our tests, this appears to be 4 times per hour.

On our end, we might change how often we update this information from time to time for optimization reasons but currently we check the user's location around every 5 minutes.

Updated about a month ago


What's Next

Add Data Tags

Location-Triggered Notifications


Tutorial - Setting up notifications that trigger based on user location.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.