Beacons

Monitor Beacons

Android

In order to start the monitoring services to look for beacon campaigns, you need to update the demographics stored in memory. Otherwise, you won’t be able to start those services and your SDK will return an IllgealStateException. You employ the following method:

D2GO.updateDemographics(JSONArray demographics, Context context)

The demographics JSONArray that’s being passed in as a parameter is structured in the following format:

[
    {
        "age":23,
        "gender":"m",
        "city":"Boston"
    }
]

The following two methods run the services to monitor beacon campaigns:

D2GOSDK.startBeaconService()
D2GOSDK.startLocationService()

But you need to run D2GOSDK.init(…) (described in Installation section) and D2GOSDK.updateDemographics(…) first to avoid getting the following exceptions:

-IllegalStateException: if not demographics found when attempting to start the service
-LoginException: if not connected to the platform
-SDKException: if not initialized

If you later wish to stop the monitoring services, you can call the following two methods:

D2GOSDK.stopLocationService()
D2GOSDK.stopBeaconService()

iOS

Monitoring Digital2GO beacons require a Beacon UUID and a Beacon Region Identifier, both of which are provided by the Digital2GO platform upon the creation of a new app.

To begin monitoring a beacon region, define the region. You define a beacon region with the appropriate initialization of the CLBeaconRegion class. An example is shown below, illustrating how the two keys (UUID and region identifier) are used to create the region to monitor.

beaconRegion = CLBeaconRegion(proximityUUID: uuid!, identifier: K.BEACON_MAIN_REGION_IDENTIFIER)

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

self.locationManager.startRangingBeacons(in: self.beaconRegion)

When a new beacon is detected, you will get notified through the didRangeBeacons as part of the CLLocationManagerDelegate protocol.

Sending Beacons

To send a beacon impression to the LOCALLY server, you use the following API:

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

You need to pass a JSON object into the API the following format:

{
    "uuid": "8D847D20-0116-435F-9A21-2FA79A706D9E",
    "device_id": "1AB422B56B3B49AF83892689ACD7246",
    "app_name": "D2GO",
    "os": "android",
    "proximity": "near",
    "bluetooth_enabled": 1,
    "type": "beacon",
    "major": "2",
    "Minor_dec": 414,
    "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" : "iPhone",
        "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 campaign that matches this impression, the campaign content will be returned as a JSON Object in the following format:

{
    "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 Beacon Input Validation Failed
  • 500 An unknown condition error means that something has gone wrong with the data on the system. This could be expected when data doesn’t exist on the system (i.e. trying to create a zone when a location doesn’t exist).

Android

To catch and handle beacon impressions, you need to create a new broadcast receiver and copy the following settings into your AndroidManifest.xml.

<receiver
    android:name="YOUR RECEIVER"
    android:enabled="true">
    <intent-filter>
        <action android:name="com.d2go.sdk.beaconimpression.your-app-name-without-spaces" />
        <action android:name="com.d2go.sdk.geofenceimpression.your-app-name-without-spaces" />
    </intent-filter>
</receiver>

You can catch the campaigns in your broadcast receiver as shown below. The campaign content is a string in the format shown previously.

public class YOUR RECEIVER extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
    String campaign = intent.getStringExtra("campaign");
    ... 
    }
}

iOS

To acquire beacon content, you use the d2gAPIRequest.postJSON method.
The method below illustrates how you’d call the API to send a beacon impression to the server. The sTargetURL variable represents the API URL and the data variable is the data in the format shown previously.

d2gAPIRequest.postJSON(sTargetURL, data: data, callback: { err, response, body in
    if err == nil {
        var strDisplayData = "Response Code: \(response!.statusCode)"
        let dictReturnedVals = body as! NSDictionary
        if response?.statusCode == 200 {
            if D2GOClient.sharedInstance.isATEnabled() == false {
                D2GOClient.sharedInstance.printAndLog(strToLog: "<**> Limited ad tracking on. Do not proceed with ads")
                return
            }
            if let success = dictReturnedVals["success"], success as! Bool {
                if let data = dictReturnedVals["data"] as? NSDictionary {
                    if let media_cdn = data["media_cdn"] as? String {
                        /*Fetch your ad JSON content here*/
                    }
                }
            }
        }
    }
}