Geofences

List of Geofences

To obtain a list of geofences around a user location, you can use the following API:

https://api.digital2go.com/geofences/inRange.json

The latitude, longitude, and location radius must be passed in as parameters to the API. Your response should be a JSON Object containing the geofences presented in the following format:

[{
    "success": true,
    "data": [
        {
            "campaign_id": 11480412,
            "coverage_type": "radius",
            "coverage": {
                "lat": 42.2251848049,
                "lng": -83.7238626206,
                "radius": 0.094
            }
        },
        {
            "campaign_id": 11480412,
            "coverage_type": "radius",
            "coverage": {
                "lat": 42.2078826275,
                "lng": -83.7164924084,
                "radius": 0.369
            }
        },
        {
            "campaign_id": 11480412,
            "coverage_type": "radius",
            "coverage": {
                "lat": 42.2130400063,
                "lng": -83.6676902903,
                "radius": 0.035
            }
        },
        {
            "campaign_id": 218962406,
            "coverage_type": "polygon",
            "coverage": "[[\"36.99130197582277\",\"-109.03752537348015\"],[\"36.99130197582277\",\"-108.63290501215215\"],[\"36.794439869911216\",\"-108.63290501215215\"],[\"36.794439869911216\",\"-109.03752537348015\"],[\"36.99130197582277\",\"-109.03752537348015\"]]"
        },
        {
            "campaign_id": 218962406,
            "coverage_type": "polygon",
            "coverage": "[[\"37.21919794859772\",\"-109.03752537348015\"],[\"37.21919794859772\",\"-108.63702488519903\"],[\"37.00630473049461\",\"-108.63702488519903\"],[\"37.00630473049461\",\"-109.03752537348015\"],[\"37.21919794859772\",\"-109.03752537348015\"]]"
        },
        {
            "campaign_id": 218962406,
            "coverage_type": "polygon",
            "coverage": "[[\"36.99239885233665\",\"-109.48796482660515\"],[\"36.99239885233665\",\"-109.05587864496465\"],[\"36.78784128360802\",\"-109.05587864496465\"],[\"36.78784128360802\",\"-109.48796482660515\"],[\"36.99239885233665\",\"-109.48796482660515\"]]"
        },
        {
            "campaign_id": 218962406,
            "coverage_type": "polygon",
            "coverage": "[[\"37.21919794859772\",\"-109.48659153558953\"],[\"37.21919794859772\",\"-109.0531320629334\"],[\"37.00630473049461\",\"-109.0531320629334\"],[\"37.00630473049461\",\"-109.48659153558953\"],[\"37.21919794859772\",\"-109.48659153558953\"]]"
        },
        {
            "campaign_id": 128780954,
            "coverage_type": "polygon",
            "coverage": "[[\"42.2640621911521\",\" -83.75024950336149\"],[\"42.26444330559502\",\" -83.74379312823942\"],[\"42.26692959740339\",\" -83.74147569965055\"],[\"42.26954281877257\",\" -83.74430811237028\"],[\"42.270359388445556\",\" -83.74972498248746\"],[\"42.2640621911521\",\" -83.75024950336149\"]]"
        }
    ]
}]

Other possible responses include:

  • 401 Incorrect Login
  • 422 Geofence Range Validation Failed

Monitor Geofences

Android

The first step in requesting geofence monitoring is to request the necessary permissions. To use geofencing, your app must request ACCESS_FINE_LOCATION in your AndroidManifest.xml, as shown in the Installation section.

The SDK uses a Service called GeofenceInAreaService to listen for geofence transitions, which is why you see this line in the example app’s AndroidManifest.xml:

<service android:name=".services.GeofenceInAreaService" />

To explore a detailed tutorial on how to create and monitor geofences in your Android app, click here.

iOS

iOS apps get location data through the classes of the Core Location framework. In your view controller, you are required to implement

the CLLocationManagerDelegate protocol of the Core Location framework.
To start monitoring the specified region, we call the startMonitoring() method of the CLLocationManagerDelegate protocol, as shown below:

locationManager.startMonitoring(for: region)

Then, you call the startRangingBeacons method, which starts the delivery of notifications for the specified beacon region.

Sending Geofence Impressions

To send geofence impressions to the LOCALLY server, you can use the following API:

https://api.digital2go.com/impressions/geofence.json

A JSONObject will need to be passed into the API in the following format:

{
    "device_id": "1AB422B56B3B49AF83892689268A9ACD7246",
    "app_name": "D2GO",
    "os": "android",
    "proximity": "enter",
    "campaign_id": "1",
    "bluetooth_enabled": 1,
    "type": "geofence",
    "lat": 33.8806158172,
    "lng": -118.3165097809,
    "demographics": {
        "gender": "male",
        "age": 23,
        "city": "Boston",
        "state": "MA"
    }, 
    "deviceinfo": {
        "ip_address6": "2601:410:4301:5d2:8df:2a:100::",
        "ip_address4": "192.168.1.1",
        "altitude": "238.378284707635",
        "battery_level": "-1",
        "device_model": "-1",
        "device_os": "iOS",
        "device_version": "10.3.1",
        "horizontal_accuracy": 8,
        "speed": "-1",
        "vertical_accuracy": 3
    },
    "timestamp": "2016-10-22 00:00:01"
}

If there is an active geofence campaign that matches this impression, the campaign content will be returned in the form of a JSON Object. It would be formatted as follows:

{
    "success": true,
    "data": {
        "id": 258946319,
        "campaign_content_touch_id": 74187960,
        "campaign_content_near_id": 74187960,
        "campaign_content_far_id": 74187960,
        "campaign_content": {
            "name": "content1campaign4",
            "description": "This is description for content 1 campaign 4",
            "notification_message": "",
            "layout": "RETAIL",
            "sub_layout": "a_name_desc",
            "check_video": "",
            "check_image": "D2GO",
            "header_title": "Header for Content 1 Campaign 4",
            "video_description_text": "",
            "product_name": "Content 1 Product Name",
            "product_description": "Product Desc for Content 1",
            "product_price": 100,
            "interaction_method": "BUTTONS",
            "campaign_content_actions": [ ],
            "campaign_content_buttons": [ ],
            "media_video": { },
            "media_image": {
                "id": 149299432,
                "filename": "24225.313251874616.1775c67dbb72648ee0bfb3bbf4c6b25d.jpg",
                "path": "uploads/MediaLibrary/24225/2016/10/19/1476840887/",
                "mimetype": "image/jpeg",
                "filesize": 220429,
                "title": "",
                "description": "",
                "width": 1706,
                "height": 1280,
                "media_status": "UPLOADED"
            },
            "id": 74187960
        },
        "media_cdn": "https://cmsdev.deliverables.digital2go.com",
        "impression_id": 2194017,
        "personas": {
            "age": "18-24",
            "gender": "male"
        }
    }
}

Other possible responses include:

  • 401 Incorrect Login
  • 404 No Campaign Found
  • 422 Geofence Input Validation Failed
  • 500 An Unknown Condition Error, which means that something has gone wrong with the data on the system. This could indicate that expected data doesn’t exist on the system (i.e. trying to create a zone when a location doesn’t exist).