Datasnap.io ingests events generated by apps interacting with beacons and running campaigns triggered by those beacons. There’s loads of info about how beacons work on the inter-web as well as a ton of beacon providers to choose from. Some beacon providers include Estimote, kontakt.io, Gimbal and many more…
The datasnap.io platform doesn’t care what kind of beacon you use to gather proximity data! You can send us data from any platform and we’ll suck it into the system and run our algos on it to understand metrics like dwell time and location engagement. We’ll create beautiful reports for you on campaign lift, user traffic in a venue and most traveled paths in a venue. You’ll also have complete access to the processed data via our Analytics API’s or your own redshift cluster.
The following document provides an overview of integrating with the system. Our complete technical documentation is hosted on Apiary. This is the source of truth for all of our technical API documentation. You can use Apiary to send test events and see how the system would work.
Contact us if you need any assistance at all support@datasnap.io
Beacons send out periodic Bluetooth low energy signals that mobile devices detect. Applications that interact with beacons can provide context about proximity and user patterns. Using this information, the app can send users notifications or other interactions. For example, Virgin Airlines places beacons near the security gate, so travelers with the Virgin app installed get their boarding passes loaded automatically when they are near the security gate. Users must opt in before the app interacts with beacons. Beacons cannot send push notifications or proximity information without consent.
Think about your core goals for these beacons:
Beacons are best placed above people’s heads and away from anything that might block the signal. 10 feet above the ground appears to be optimal.
Place beacons where they will be visible to people’s mobile devices. Beacon signals generally range from inches to about 300 feet. Signals can be affected by physical barriers, such as walls, people, or structures. Placing beacons in a clear, unobstructed area will improve results.
Some beacon vendor signals are more consistent than others.
If your app needs to know how close users are, place as many beacons in the targeted area as possible. Ideally, a person should be sighted by 3 or 4 beacons at all times within the targeted area.
Likewise, if your app needs to determine when someone passes by, place a high number of beacons in the area to better detect how close people are. This is useful for measuring wait times, queue times, etc.
Alternatively, to simply determine whether a person is present, set up a zone or place to detect when users are in the area. Group a number of beacons together to to define a place or zone. Accuracy is not as important with places, and this grouping effectively determines when a user is near or far from that place.
Measuring distance from signal strength (RSSI) is a tough task because RSSI is easily affected by its environment. RSSI signals can be blocked by walls, people, and structures. It may also be reflected by various objects, resulting in a very noisy signal. Beacon and mobile device orientation also affect RSSI, making it difficult to infer accurate distance information without deep knowledge of the physical location and the beacon.
A possible solution is “fingerprinting,” whereby a table of expected RSSI values corresponds to various places of interests. Compare user’s readings to this table to improve triangulation.
Most beacon providers give you a way to monitor the beacon battery.
If possible, mark beacons with Latitude and Longitude coordinates.
Beacons can be plotted on a map using Lat/Long coordinates. This is useful for displaying population density data on the map.
This usually works best in large spaces like a festival or stadium.
Group beacons by tagging them: assign them to a place or tag them with labels.
Beacon groups are better at tracking movement and pathing than singular beacons.
Tags identify beacons zones, useful for studying visitor density and pathing to other zones.
Manufacturer | Details | Price | Spec |
---|---|---|---|
Gimbal |
|
Small: $15 for 3 beacons Large: $20 |
Gimbal Spec |
Estimote |
|
Large: $99 for 3 beacons Stickers: 10 for $99 |
Estimote Spec |
Kontakt.io |
|
$81 for 3 beacons | Kontakt.io Spec |
Radius Networks |
|
USB: $29 Tag: $39 |
Radius Networks Spec |
Parent organization for the organizations and venues. This will be provided for you by a datasnap.io representative. Contact support@datasnap.io to get started.
Datasnap.io segments data and permissions around the notion of organizations. Venues and apps are associated with an organization, so when you send in an event into the system it must always have an associated organization_id.
Venues represent a physical location where a beacon is placed. You must always send in venue_org_id with an event. Sometimes you might not have a venue, for example you may have put beacons around the streets of London. In this case you can do something like send in ‘Unclassified’ with the event or send in ‘London’ as the venue. Venues are really just another way to segment your data.
You can now separate advertisers from organizations. This is typically used in a network model when clients are running campaigns on their apps on behalf of an advertiser who does not own the app or the venue.
Projects are a way to further segment data. Projects are typically apps (eg: My Cool Android App, My Cool IOS App). A sub-organization may have one or many apps feeding data to it. and project_id along with every event.
Places are a further breakdown of locations within a sub-organization. You can use places to group beacons or geofences together. We recommend grouping sets of beacons together into places - like stage left, stage right, front entrance etc. Places are critical to building out and visualizing paths people take from one location to another. For reporting purposes we recommend using as many beacons as you can to group them into places, so people walking around are seen by as many beacons as possible.
In a typical setup the entity who owns the app, runs campaigns and owns the venue are all the same organization. In other words you are running campaigns and collecting user location data on behalf of one organization that owns the entire system.
In a network implementation the key difference is that the entity running campaigns may be a completely separate organization from the owner of the app or the venues. For example coke may run a campaign on a team app at your stadium.
Organizations perform two key functions in the system.
They represent a group to which you can assign users
Users are either administrators or read-only users
They are owners of entities in the system
Entities are apps, venues, beacons, places, geofences and advertisers
The San Francisco Panda Ant’s are playing World Team Tennis at Membley Stadium and Bob’s Cola wants to run a campaign on the Tennis app while people are in the stadium.
“Bob’s Cola” is created in the system as an Advertiser and campaigns are run under “Bob’s Cola” advertiser on the Tennis app. Campaign events are captured and sent to the datasnap.io servers from the tennis app.
There are two core API’s for getting the data into the system…
Use this API to send events into the system from your app. These are events like beacon sightings, beacon entry and exit events and campaign clicks. This API is used to capture all the events you want analyzed in the system. Event API Reference »
Use this API to get entity’s into the system. You can think of an entity as a thing that can have meta data attached to it e.g. a beacon. A beacon can have meta data describing it like a description or a lat / long or battery life. Entity API Reference »
There are several important id’s in play when reading and writing data from/to the system. These id’s determine how data is segmented and permissioned.
1. organization_id: This can be thought of as a group. Every entity in the system is owned by an organization. When sending in an event the organization_id is ALWAYS the owner of the app.
2. advertiser_org_id: Used when sending campaign events. This is the advertiser that is sending the campaign event
3. venue_org_id: This is the venue that the beacon is located in
4. project_id: This is the application that generated the event
You send in the following entities using the Entity API
You send these entities in along with descriptions and any other information like lat / long, battery level, floor and so on.
Using this methods you can have control of which entities appear in reporting and which should be used for generating pathing in reporting.
To use this method you must set the appropriate flags on the organization: http://docs.datasnapioentityapidev.apiary.io/#reference/organization
See documentation on setting up Beacons, Places and Geofences via the entity API docs.datasnapioentityapi.apiary.io
NOTE: You do not need to send in campaigns via the Entity API.
The typical JSON datatypes are in play when sending data: http://en.wikipedia.org/wiki/JSON#Data_types.2C_syntax_and_example
Property Name Rules
Property Value Rules
Dates
All dates should be represented as ISO 8601 formatted dates and include the timezone. http://en.wikipedia.org/wiki/ISO_8601
UTC Time
PST Time
We have the following top level properties that represent the current domain when dealing with proximity data and events. These properties can automatically be updated or they can be updated as part of our Entity API. You must pick one approach to use you cannot do both at the same time. Also note that the entity API will provide for more advanced insertion of data to be used in your reports in the future.
docs.datasnapioentityapi.apiary.io
Name | Description |
---|---|
organization_id | organization id assigned to you |
advertiser_org_id | advertiser id sent along with campaign events |
venue_org_id | the venue that this event is associated with |
project_id | Project id within that organization (typically app) |
event_type | The type of event you are sending - beacon_sighting, geofence_depart etc. |
global_distinct_id | the unique user id associated with this event |
To get beacon reporting send in a minimum of a sighting event.
To get place pathing you need to associate beacons with places.
To view campaign reporting send in a communication event with a campaign.
To get geofence reporting send a geofence_exit event.
To see GPS reports or user movement send in a GPS event.
The core events to send are listed below
Quickly add, update, or delete datasets to the datasnap.io platform via a CSV file. Use curl commands in the terminal to upload data to the datasnap.io server.
A 200 response returns when a CSV upload succeeds. To get more information about the upload, use the verbose=true
flag in the URL of the HTTP request.
"https://entities.datasnap.io/v1.0/beacon_entity_upload?organization_id=##############&verbose=true"
[{"UPDATED":{"venue_org_id":"TEST_venue_1","name":"TEST_name_1","identifier":"TEST_id_1"}}
,{"UPDATED":{"venue_org_id":"TEST_venue_2","name":"TEST_name_2","identifier":"TEST_id_2"}}
,{"CREATED":{"venue_org_id":"TEST_venue_5","name":"TEST_name_5","identifier":"TEST_id_5"}}]
One Place the in CSV did not exist.
[{"DELETED":{"venue_org_id":"1tIaudT6OqBKCLhCC4LliE","place_type":"physical_place","name":"The Place Name","id":"place-id"}},{"NOT FOUND":{"venue_org_id":"1tIaudT6OqBKCLhCCaLliE","place_type":"physical_place","name":"Place 2","id":"Place2-id"}}]
A 400 error response returns if the CSV file is improperly formatted. Some common mistakes are:
Below are the required columns to upload beacons via CSV. Download a Sample Beacon-Upload CSV to see an example.
Name | Description |
---|---|
Action | Whether to add or delete a place. Use A for add/update and D for delete |
venue_org_id | Unique id for the organization |
name | Optional beacon name, often a venue name |
identifier | 10-digit string identifying the beacon |
Be sure to pass your organization ID into the URL. Use the optional Verbose flag to see a detailed response.
curl -X POST "http://entities.datasnap.io/v1.0/beacon_entity_upload?organization_id=##############" \
-H "Authorization: Basic MkJMTFUxTDJOUjgxOThZMDVZWVFXQ1pDMjpJd0NpSG41T1VXOCtUFFNkVUYW1XXQ1Q0TENvNFRabEc0eXBhZ0FSbmlV" \
-H "Content-type: application/json" \
--data-binary "@beacons2.csv" -v
Below are the required columns for a place-upload CSV file. Download a Sample Place-Upload CSV to see an example.
Name | Description |
---|---|
Action | Whether to add or delete a place. Use A for add/update and D for delete |
id | Place id |
name | Place name |
place_type | Value can be physical_place or logical_place |
venue_org_id | Unique id for the organization |
Be sure to pass your organization ID into the URL
curl -X POST "http://entities.datasnap.io/v1.0/place_entity_upload?organization_id=##############" \
-H "Authorization: Basic MkJMTFUxTDJOUjgxOThZMDVZWVFXQ1pDMjpJd0NpSG41T1VXOCtsWUFFNkVUXX1jQ1Q0TENvNFRabEc0eXBhZ0FSbmlV" \
-H "Content-type: application/json" \
--data-binary "@places2.csv" -v
Below are the required columns for a place-beacon-upload CSV file. Download a Sample Place-Beacon-Upload CSV to see an example.
Name | Description |
---|---|
Action | Whether to add or delete a place. Use A for add/update and D for delete |
place_id | Place id |
beacon_identifier | 10-digit string identifying the beacon |
Be sure to pass your organization ID into the URL
curl -X POST "http://entities.datasnap.io/v1.0/place_beacon_upload?organization_id=##############" \
-H "Authorization: Basic MkJMTFUxTDJOUjgxOThZMDVZWVFXQ1pDMjpJd0NpSG41T1VXOCtsWUFFNkVUY1jQ1Q0TENvNFRabEc0eXBhZ0FSbmlV" \
-H "Content-type: application/json" \
--data-binary "@place_beacons2.csv" -v
The datasnap.io analytics API can be used to pull data into any system and has a set of pre-configured ways to slice & filter data. You can return multiple metrics at once or just a single metric. You can filter & group data in a variety of ways. All data is returned in JSON. Note that this API is concerned with filtering events.
Analytics API: docs.datasnapioentityapi.apiary.io
Use the Entity API to pull back the entity ID’s to use in the Analytics API call. For finding and retrieving Entities such as place/Beacons please use our Entity API located at: docs.datasnapioentityapi.apiary.io
"global_position": {
"location": {
"coordinates": [
37.7833,
-122.4167
]
},
"altitude": 13,
"accuracy": 10,
"course": 77.34375,
"speed": 4
}
This is the Datasnap SDK Release 2.0.0 for Android and iOS.
Datasnap iOS SDK
Datasnap Android SDK
Apps integrating with Gimbal can leverage a pre-defined method that sends default events to the Datasnap SDK with a quick turnkey solution.
Pre-defined list of event-type methods lets developers quickly send an event with default configurations.
Improved logging and troubleshooting.
Configurable batch sizing and timeout threshold.
Event compression for better app performance.
Offline caching collects data when the user goes offline and sends it after they come back online.
Data collection for OS, Version and manufacturer information improves reporting.
Data collection is defaulted to on for Google Ad ID/Hashed email/Device info for Android and Hashed email/Device info for iOS, so long as a user has allowed their device to collect that information. If your privacy consent with end users does not allow sharing this data with Neustar, you MUST override the default setting.