Documentation Overview

Beemray audience intelligence platform merges your digital and physical worlds, provides you with enlightened insights on user behaviour and their ecosystem.  

Beemray platform enables to build unique, real-time audiences using algorithms based on location and place visits. In addition, in-app behavior, on-site behaviour, event attributes, user profiles, time, engagement metrics, app usage & other external data across all channels can be used to enhance the audience development.

This can all be administrated and managed within the Beemray Honeypot.
Honeypot is the online interface for Beemray audience intelligence platform that enables data analysis, gaining insights and audience building capabilities.  

Beemray documentation provides you with understanding and means on how to make the most of Beemray’s service portfolio.
It consists of developer docs along with implementation and user guides.

In case you don’t find an answer to your needs, please contact our support, we’re happy to help!

Send message to: 
BEEMRAY Support

BEEMRAY PLATFORM

The Beemray platform provides a wealth of functionalities and features that enable data collection, analysis & insights and audience building.

The following diagram illustrates the high level architecture of Beemray Platform:

beemray_platform

BACKEND

The backend is designed to handle extreme load, performance being always one of the key values in the platform design. Standard and well-known technologies such as J2EE and PostgreSQL are utilised in all implementations, to ensure the best overall efficiency and availability, empowering us to scale the system. The backend servers are running in clustered environments in a cloud.

Our open, standards-based REST APIs allow advanced companies such as agencies, brands and integrator partners to deeply integrate Beemray’s functionalities into the tools and platforms they use every day.

DATA ANALYSIS

Analysis and modeling components make up a big part of the platform’s data stack. Various devices generate large volumes of data that offer vital insight into the performance of the account data and audiences. Additionally, they provide critical input to model tuning.

AUDIENCE MANAGEMENT

Beemray enables to build target audiences using algorithms based on location, in-app behavior, event attribute, profile, time, engagement metrics, app usage & other external data across all channels. The target audiences are the backbone of personalised push, in-app, and browser targeting, but they also drive connections outside the Beemray ecosystem as well. Integrate audiences to your DMP, CRM, ad servers etc to reach your users and drive better targeting.

The cool thing about Beemray audience building capabilities is that it enables utilisation and combination of any, also self-created, elements. To make it even more versatile, it also allows nested structures, and selecting any operator within an a target audience. The flow of filling a user into an audience is dynamic, real-time and always up-to-date updated. Therefore an audience usually starts as an empty audience until user behaviour fulfills audience rules. Thereafter the number of users in an audience can be constantly changing.

AUDIENCE ATTRIBUTE TYPES

Audience is a subset of devices which fulfill all the specified attributes within the audience. An audience contains one-to-many attributes based on user behaviour. Each of these attributes can contain conditional operators if the event fulfills this single attribute.

An audience can contain three types of attributes:

  1. Place location attribute defines the current location (lat/lon) of the user/device.
  2. Event attribute describes a triggered event based on user behaviour. Single event can contain simple key-value-type structured data elements together with a event’s title. As an example we can take the event”ADD_TO_CART” as an event title containing values of “PRODUCT_TITLE”, “PRODUCT_PRICE”
  3. Profile attribute describes demographical information that user has defined in the application about himself/herself like gender, age, marital status and hobbies.

COMPARISON OPERATORS

Each attribute type has a different kind of condition option to check if the corresponding value from an event passes the condition rules of the attribute. Supported comparison operators for numeric attributes are < (less than), > (greater than), (equals or less than), (equals or greater than) and = (equals).

Supported comparison operators for textual attributes are “ilike” (case insensitive partial match), “like” (case sensitive partial match) and “=” (equals to). Also, a well-known regular expression matching is supported.

Supported operator for location attribute is always full comparison if given location is contained by the spot which has been set as an attribute. Each spot is geographical area of the map.

3RD PARTY DATA SOURCES

The platform’s open APIs provide integration points for external data sources to

  1. Enhance context understanding of a consumer for analysis purposes
  2. Enable behavioral data to be completed by a 3rd party data source such as CRM
  3. Establish a 3rd party data source as a part of the rules to trigger marketing automation

3RD PARTY INTEGRATIONS

The platform enables integrations with a growing number of external platforms. The audiences that are created in the Beemray platform, can be sent to other platforms as audience enhancements or as completely new audiences for more granular location-driven targeting.

User State

User State is the result of an identification process inside the Beemray Audience functionality.

This feature enables us to gain an understanding of the user’s previous actions in addition to the current session.

This way we can identify and specify the user behavioural patterns, not just within the Beemray service, but in co-operation with external partner platforms such as Lotame DMP or Google DFP.

Any IDs Beemray is using are GDPR compliant, we do not save any PII on users.

How does it work?

Most web-pages contain identifiers that include the IDs for different services.

While creating a Beemray Audience, the desired page url is configured as a rule of audience fulfillment. Once a user generates an event, for example SDK load or page load on a specific page url, Beemray collects that data and sends it to external partners stating that this user ID has fulfilled a Beemray Audience.

The same user visits another web-page that has been configured in the same Beemray Audience, creating a record of that same user fulfilling an audience again, only in a different page url.  

As the user again generates an audience fulfillment, the data is sent to Beemray’s database for validation. Beemray database identifies the user as an already existing “old” user, resulting in not collecting the userID again. This way the Beemray Audience only contains the unique userIDs.

Beemray Audience sends the collected audience data, including the new user IDs, to external partners on an agreed frequency.  

Depending what the partner prefers, it is possible for Beemray to send only the data that has changed since the last export, or the whole data batch containing all data over to external partners.

What are the benefits?

User State enables us to gain a better understanding of the unique users in a Beemray Audience, versus the total amount of Beemray Audience fulfillments.

It significantly improves the quality of user behavioural data giving insights on the user behavioural patterns.

User State also makes it possible to send out Beemray Push Notifications to individual users, preventing each user getting repetitive push notifications of the same campaign.

As a bonus – User State also lightens the data load at the partner DMP-end, as the user is already identified in the Beemray database. This prevents multiple hits per unique user being sent to partners.

 

Privacy

Data

We take privacy seriously and make sure that no personal data of the end user device is stored in our service. We only keep track of the device using non-identifiable (aggregated and anonymised) UIDs.

Beemray collects data using scripts and similar techniques. These technologies are used to track online actions of consumers that visit the websites, mobile applications and digital properties of our customers. We also receive supplemental contextual data from third parties such as weather. We do not use 3rd party cookies.

In some cases we may collect personally identifiable information on behalf of our clients which they retain subject to their privacy policy and it is used by Beemray for reporting purposes only.

Location data (lat/long or IP) of a device is processed by the device SDK and is only utilised to determine if a device belongs to any audience. The process is fully anonymised, no personal identifiable information (PII) is stored in the Beemray audience intelligence platform.

For a website standard policy, we recommend our customers to have a clause in Terms & Conditions explaining that non-identifiable location tracking may take place when using the site.

For above reasons and more, Beemray technology is compatible with the valid EU Directive 95/46/EC and the upcoming EU Regulation 2016/679.

What kind of data does Beemray collect?

Beemray collects data to help our customers understand behaviour of their customer. To do this, we use the data we collect to operate and improve our software, services, and devices, to enable personalised experiences and to gain insights. These are some of the most common categories of data we collect.

Visited places

Location information helps to provide info relevant to where a consumer is. For this, we use the locations that we have detected using technologies like GPS or IP addresses.

A consumer can turn on or off location services in the settings of the device.

Location behavior

Location behavior is automatically compiled from the device movement to formulate attributes such as home, work, commuting etc. The behavioral attributes are anonymized and can be used along with any audience.

IoT signals

There are a lot of non-traditional data signals readily available. Beemray invests in introducing new signals to enhance audience profiling. Beacons are a great example of a well-established IoT signal.

Custom Events

Custom events enable our customer to utilise website and app events such as clicks for enhanced audience profiling.

Web browsing

When a consumer reads articles on the pages that include Beemray technology, we may use the keywords of the page content to better understand the context. The keywords can be used to fulfil audiences.

A consumer can choose whether browsing history is collected via browser privacy settings.

Information from device sensors

As you would expect from any modern device, most phones, tablets, and PCs come with sensors – ways for the device to detect the world. That can be phone’s accelerometer,, an internal GPS sensor, and more. Beemray is constantly exploring the possibilities improve contextual understanding of the device while, naturally, maintaining high-level of privacy.

Data enables to show more interesting content or ads

Beemray’s audience intelligence platform enables personalisation including advertising. To show ads that the consumer is more likely to be interested in, we use data like location, weather, advertiser web page content, demographics, and things that matter in the context.

To stop Beemray from providing personalised ads or content based on interests, a consumer may use our Reset My Data -controls online.

Go to the online Reset My Data -page

GDPR

As a data processor, we are working to earn trust every day by focusing on four key privacy principles:

  • Control: We control of privacy sensitive data with easy-to-use tools and clear choices.
  • Transparency: We are transparent about data collection and use so you can make informed decisions.
  • Security: We protect the data you entrust to us through strong security and encryption.
  • Legal protections: We will respect local privacy laws and fight for legal protection of privacy as a fundamental human right.

These principles form the foundation of Beemray’s approach to privacy and will continue to shape the way we build our products and services. And we are constantly working to improve, so if you notice something in our products and services that does not work the way you would expect when it comes to privacy, please let us know.

Furthermore, we have made significant investments to prepare the business and our clients’ businesses for the GDPR. This includes conducting a Privacy Impact Assessment, updating our Data Protection Agreement, appointing a Data Protection Officer, assembling a GDPR Taskforce, and dedicating engineering resources to enhance the platform with additional GDPR compliance features.

Preparing for a new era in privacy regulation

Beemray has extensive expertise in protecting data, championing privacy, and complying with complex regulations, and currently complies with both EU-U.S. Privacy Shield and EU Model Clauses. We believe that the GDPR is an important step forward for clarifying and enabling individual privacy rights. We want to help you focus on your core business while efficiently preparing for the GDPR.

We are committed to GDPR compliance across our services, and provide GDPR related assurances in our contractual commitments.

Data Reset

We at Beemray take pride in being GDPR compliant, and therefore want to offer our users a chance to opt out from any data collection. A user is able to ask for a User Data Reset, that will erase all data that has been collected of the said user’s behaviour.

Our IDs are never personally identifiable, but anonymous auto generated IDs matched with the cookie ID that comes from the user’s browser when using the web, or app ID when using a mobile application.

We have a ‘Reset my user Data’ web page under Beemray.com. 

Our customers and partners can also guide the users to that address for user data reset.

Web flow

Beemray Web SDK contains Javascript API which allows users to reset data that was collected from them.
 

Prerequisites

  • The Beemray Web SDK must be available on the host website where the reset functionality is implemented for a user.

Using the Data Reset API

This will clear all the Beemray’s user data from the browser and the Beemray platform.
 
Example: A data reset button
Note: The user needs to submit the request using the same browser the data has been collected from to be able to reset the correct user data.

 

App flow

  • A user clicks Reset my user Data within the app

As a result of the submitted request the following will happen:

  • Beemray platform receives a request to reset the user data.
  • Beemray will reset all data related to that specific user from Beemray’s platform.
  • Beemray will send a request for all integrated partners to reset all data related to that specific user.
  • Beemray data will be reset immediately. Integration partners are responsible for deleting the requested data according to their respective reset processes.

Note: Any data that has been already aggregated into un-identifiable general sums and values in Beemray Honeypot Analytics, will not be deducted due to a user data reset.

Location Crowdsourcing

Beemray uses patent-pending location technology for mobile web. The sophisticated system is based on machine learning algorithms that constantly improve the accuracy of our global location database. Our platform analyzes location data from different connection types and methods of hundreds of millions devices every day, in real-time, and cross-utilizes data for tuning accuracies. We call this “Location Crowdsourcing”. It ensures that our customers can always rely on the up-to-date location data for engagement and targeting in mobile web.
 

Data Collection

Data Collection Method 1 – No Consent Requests


Our default method for location data collection on any site using http or https connections. The method crowdsources lat/longs derived from all connected devices and verifies location accuracies against our global location database.


Support
All browsers and devices that are connected to a wifi or fixed network.

Action
The user location sharing is performed automatically without user consent request of the browser.

Benefit
Enables location tracking for every user that visits your sites. Beemray machine learning algorithms constantly analyse location data.



Data Collection Method 2 – Location Consent Request on Https Sites


This is a method for location data collection on any site using secure https connection (Example: https://www.theguardian.com). It enables accuracy down to few meters, similar to mobile apps.


Support
All browsers. All varieties of Internet connectivity.

Action
The site requests user to permit location sharing with a standard browser notification. A browser asks a user once for location sharing. There are some variations depending on browser manufacturer and OS. By default Chrome asks consent only once, Safari once per day, Firefox once per page.  

Benefit
Enables precise location tracking.


Data Collection Method 3 – Mobile Applications


This is a method for location data collection from a mobile application using https connection. It enables accuracy down to few meters using GPS, wifi, and beacons.


Support
Android
iOS  

Action
The mobile application requests a user to permit location tracking during the app installation process. The app user can prohibit the location tracking later disabling it in the device settings.

Benefit
Enables precise location tracking.

Audience Data Contents

The audience building process follows a distributed architecture and maintains user anonymity in all phases.

The device captures location and contextual data with Beemray SDK. The device location is captured using long/lat coordinates, IP or a combination of both. However, no coordinates, IP information or even device id’s are stored against the device, just the possible audience relation the device has pre-processed and sent to the platform.

Thereafter the platform analyses data to define if the device behaviour fills all the audience rules, and the platform returns the audience data to the device SDK. The device SDK then sends it to external platforms when needed.

Audience data is collected for the purposes of Beemray Honeypot analytics and performance metrics, and it includes a cumulative amount of lat/long data but not any identifiers of a single device. The whole audience building workflow is fully automatic, real-time, non-identifiable and does not include manual input.

Audience Data Flow for Web

1. A consumer makes a HTTP request from a browser (www.mirror.co.uk as an example) which exposes an IP of a client to the server. The host web page exposes a user id of a DMP on this web page. This id is never sent or stored to Beemray platform.
2. Platform resolves the location for the IP. Based on this location, a request filters matching location of defined audiences, time of day, day of week or other general attributes.

3. Our platform pairs the audience id with external platform’s audience id. When a consumer request fulfills Beemray audience rules, the platform returns the audience id of the external platform back to the browser.

4. Browser makes a request to this external platform – with the user id the host web page has exposed – with the external platform’s audience id as a parameter to signal that the consumer has fulfilled an audience on Beemray’s platform.

The dataset to be stored from an individual audience fulfilment is location (by four decimals) where from audience has been fulfilled and timestamp when audience has been fulfilled. It does not include any device or user identifier.

Personal Status

Beemray Personal Status is an add-on-service, to deepen-, and further define, the understanding of the clients behaviour. It offers an additional dimension to targeting, increasing the conversion by being able to target to a more relevant segment of people.

It is based on an algorithm that uses the Beemray matrix containing client values from a longer period of time.

During this time we’ve gathered multiple entries from each client, from multiple locations, times and actions (page loads). Based on these values, we apply the matrix logic and and perform the calculation and analysis to identify behavioural patterns.

These patterns are categorised as follows:

  • Home
  • Work
  • Commuting
  • Freetime
  • Travel
  • ReturnFromTravel

We don’t identify individuals as users or personas. We identify the browser client. First time the browser sends an event to our backend, we generate a client ID for each browser to identify the same client going forward.

We don’t have cross-device support, so we’re unable to identify multiple devices for one user. All Beemray services are based on this same client logic; both Audiences and Personal Status.

Personal Status Definitions

Home:
The location where you spend the most time outside from Work, and where you frequently are on daily basis during evenings and nights.

Work:
The location where you spend the most time time outside from Home, on typical working hours, on daily basis mon-fri.

Commuting:
Not at Home and not at Work, you’re on the move on specific timeframes before- and after the typical working hours.

Freetime:
Not at Work or Commuting. Your time spent outside of the typical working- and commuting hours.

Travel:
Located over 100km from Home, and you’ve not been identified to be either at Home or at Work within a certain period of time.

ReturnFromTravel:
Personal Status has changed from Travel to Home or to Work. ReturnFromTravel-status remains active for a week after the status change.

Personal Status Algorithm

First Beemray analyses and identifies Home and Work for each client. Based on those we calculate Commuting, Freetime, Travel, and ReturnFromTravel.
If both Home and Work are not identified, other Personal Statuses are not available either.

Each Personal Status is defined based on a number of variables related to the client’s location, day of week, time of day, already identified patterns of behaviour, their weighted values and their relation to each other.

Identifying Behavioural Patterns – Beemray Algorithm

To be able to define the Personal Statuses in their full accuracy, in an optimal environment and amount of activity, the most active clients are able fill the matrix after a week. With less active clients, it takes 2 weeks at a minimum.

So, after implementation, at least 2 weeks time should be allowed for us to gather data before expecting to see results from Personal Statuses.

This method enables for us to identify the clients behavioural patterns, such as at what times the client typically is at Work and what time at Home. Based on those, we identify exact time windows (right before and after being at Work) when we assume the client is commuting if it is not at Home or at Work during that time window.

The algorithm is ever evolving – We continue to develop it as we go along and as the data gathers.

Beemray Audience vs Personal Status

The standard Beemray Audience is based on the client to perform a page load on customer site while located anywhere within the selected geographical location (ie London) stated in the Audience, regardless of what the Personal Status is, and regardless of what we know, if anything, of the client otherwise. Client location either fulfils an Audience or doesn’t, no calculation is needed.

Beemray Audience fulfilment is totally an independent action from the Personal Statuses.

Sources

One part of Beemray’s service is to identify the context and content a user is interacting with.  Sources help to identify what content the users are consuming. Sources enable deeper insight on user behaviour and attribution. It can enrich the location data with connected intelligence between online and offline user behaviour. As with all other elements of the Beemray product, this happens in real-time.

Beemray Web Source

Web Sources

Web Source defines what kind of SDK is shared to the site and when the SDK is shared with the site.

It identifies the traffic source and implicates what data is imported back to Beemray.

In order to create a Web Source, the customer first needs to have the full integration setup done and create a Beemray account.

Web Source is always account-specific, and it can be configured and managed within the Beemray Honeypot ‘Web Source’ section under ‘Audience’.

 

Web Source workflow

Web Source is a configuration that defines when the SDK will be loaded on site, and what kind of SDK it is. This is done via a loader that is set on the customer’s site. Loader functionality is described in Integration section.

When a page load happens, the SDK loader sends a request for an SDK load and based on the Web Source configuration, the Beemray server will either return the matching SDK on site or return nothing if no matches are made. The latter will result in SDK not loaded on site.  

Beemray server checks the Web Source configuration in a vertical order from top down, the first rule that matches the corresponding SDK configuration is returned on site.

The order of Web Source configuration rules is adjustable.

Pro Tip: Most generic URL rules are advised to be set on the bottom of the list, this ensures the SDK gets a configuration back on site.

Web Source Configuration Features

Configuring the Web Source

Web Source defines the SDK, which features are used, and when the SDK sends events to the server.

URL rule is based on the source page from where the SDK loader is trying to load on site.

The rule is a absolute URL (path) or a Regex syntax prerequisite that when fulfilled, the request is replied with the configuration attached to the rule.

GPS (on/off)

When the GPS selection has been set to ‘ON’, when loading the web page, a user will get a screen pop-up in their browser requesting for a permission to know the user’s location.

If the user gives such permission, the location accuracy is geographically exact.

If they don’t give the permission, user location accuracy is based on the location of the IP address. IP address locations are not an exact geographical location, but a wider range.

IP location can be made more accurate by using Beemray’s patent-pending location technology for web. The sophisticated system is based on machine learning algorithms that constantly improve the accuracy of our global location database. Our platform analyzes location data from different connection types and methods from hundreds of millions devices every day, in real-time, and cross-utilizes data for tuning accuracies. We call this “Location Crowdsourcing”. It ensures that our customers can always rely on the up-to-date location data for engagement and targeting.

When using the GPS or Push Notification features, the site where it’s used needs to include HTTPS protocol.

Events

Events are user interactions with content that can be tracked independently from a web page or a mobile application. Buttons, pageviews, pictures etc, practically anything clickable, are all examples of actions you might want to track as Events.

Events are useful in understanding behavior of users on your web or mobile application because Events allow drilling down and grouping data to be more intuitive and flexible. This means that you can use better targeted segments and you will have more accurate data to play with when doing marketing.

Beemray has three types of events:

Built-in events, Browser events and Custom events.
Built-in events and Browser events can be chosen to be included in the web SDK, and their configuration alters the web SDK functionality.
Custom events are not managed via the Honeypot UI, they are built using the EventAPI and are inserted directly to web site source code by the customer.
Honeypot UI only includes an option for the admin to choose those custom events as web source rules once the custom event scripts are in place on site. In order for a Beemray audience to be fulfilled, the custom event needs to be set as a web source rule and the custom event script needs to be on site. 

Built-In Events

  • “webSdkLoaded”: Sent each time the SDK is loaded.
  • “personalPlaces”: Sent each time SDK detects the latest timestamp is older than one hour.
  • “notificationOpen”: Sent whenever a user interacts with the received notification.
  • “notificationReceived”: Sent whenever a notification is received.

Browser Events

The Web SDK enables the user to create a browser event. Browser events can be attached to any HTML event. The logic is similar to other script management tools.

The number of events is not limited, and there are no rules dictating the order the events have to be performed.

Each event is always independent and they can’t be chained together.

Action is:

Target is:

Event name is:

 

Browser elements could include e.g.

• Action: Click

• Target(CSS selector): Button ID #banner

• Name: Newsletter order

• When building an audience, you can choose which events you want have included in an audience.

Browser event:

Custom Action Target Name

Click #banner Banner click

Custom Events

Custom events are built using the Beemray EventAPI and are inserted directly to web site source code by the customer.
They are not managed via the Honeypot UI,  Honeypot UI only includes an option for the admin to choose those custom events as web source rules once the custom event scripts are in place on site. 

In order for a Beemray audience to be fulfilled, the custom event needs to be set as a web source rule and the custom event script needs to be on site. 

Read more about custom events under the EventAPI section: https://documentation.beemray.com/ver7/#event-api

Application Sources

Application Source is an SDK configuration that defines how the application is integrated with Beemray’s service. For the SDK integration to be successful, the app developer needs to include a customer-specific API key provided by Beemray. Detailed integration instructions for all platforms are found in the Application SDK Integration Instructions.

When the SDK is included in the application, the app starts collecting data from the moment the user starts it for the first time. This data includes location and other contextual information such as the country, operating system or surrounding beacons.

Application Source Configuration Features

A running application containing Beemray Application SDK will be able to send events to Beemray server as well as receive push notifications from Beemray.

Application SDK Events

Different events can also be identified and measured from the Application Source.

The following Mobile SDK events are the default:

  • “activity”: Sent whenever user location changes by more than displacement meters (50m), if at least rate seconds (30s) have elapsed. An event is triggered at the time which ever parameter is met first. Both conditions (distance and time) must be met before a second event is sent.
  • “appInstalled”: Sent only the first time Beemray service starts after installation. (Sent again if app is removed and reinstalled)
  • “sdkStart”: Sent every time the service is started. Normally, this is whenever the app is started, either by user or by the OS.
  • “appEnter”: Sent whenever app comes to foreground.
  • “appExit”: Sent whenever app goes to background.
  • “personalPlaces”: Sent each time SDK detects the latest timestamp is older than one hour.
  • “notificationOpen”: Sent whenever a user interacts with the received notification.
  • “notificationReceived”: Sent whenever a notification is received.

Push notifications

Beemray enables the creation of application-based push notification campaigns to reach audiences real-time.

Push notification campaigns are a one-way communication channel towards the end-users, without them having to interact.

Campaigns can be built to reach desired audiences. Once the audience is created and selected for the campaign, a preview of the target audience size is provided by Beemray.

All push notification campaigns are measured and analysed, and the results are displayed in the Honeypot Analytics Push-section.

GEO Restrictions

Sometimes there might be a need to filter and restrict the amount of audience fulfillments.

In areas that are highly populated, and the need is to target only users on a very specific location, and exclude users that are within the nearby area, GEO Restrictions come in very handy.

GEO Restrictions feature is based on functionality that before any data is collected, Beemray backend checks whether the SDK is within the configured areas. If it is, then the device’s request is included as according to the process, if it is not, then any information will be disregarded and the device will not be included in a audience.

Honeypot

Beemray Honeypot Dashboard

Accounts

An account is the basis for the Beemray service. It contains all account related data, such as account name, ownership, user rights and the contractually agreed setup with the customer.

Each account has a unique account ID. This account ID is included in the script/API Key the customer will insert this into their website/APP/web server.

Beemray’s Honeypot has an ‘Accounts’ view under the ‘Settings’ view, from which a user can find a listing of all available accounts for that userID.

The created accounts will also be listed in the Beemray Honeypot Analytics view for the user to see data related to each specific account.


Each account contains the following elements:

  • Account info
    • Account name (Unique and cannot be changed later)
    • Created date and time
    • Account description (free text field)
    • Owner email
  • Owner
    • name
    • email
  • Users
    • name
    • email
  • Integration scripts
    • Web SDK
    • API key
    • Push Notification script
    • iOS/android SDK

 

Parent Accounts

Parent accounts are the top level customer accounts.

The initial parent accounts are always created and owned by Beemray, based on the info the customer has provided for Beemray.

In order to ensure no data is lost, and there will no misuse cases, Beemray will manage the parent accounts. Additional accounts can then be created by authorised users stated in the parent account.

 

Account management

Account users can only be invited via email from the Honeypot UI, and each new user needs to log in via the link in the email. Once the user has successfully logged in, they can manage the account and add more users.

Honeypot UI includes separate views for accounts and user management.

Each account has owners and users. All users are admin users and have equal user rights.

Account owners will receive all account and service related communication from Beemray via email.

 

Create new users to an account

Users can only be invited using an email address, not created solely in the system. This can be done by logging in to Honeypot account settings and sending an email invitation to the user. Upon their confirmation, a new user ID and account association has been set.

If the invited user does not have a Beemray user ID yet, they will be provided with a link to create one. Once created, they will be guided to confirm the account user ID.

If the invited user already has an user ID, they will receive an email notification of the new account association.

 

Change an account owner

Account ownership change is done by assigning a new owner for the account.

This happens by logging in to Honeypot account settings and sending an email invitation to the user. Upon their confirmation, a new account ownership is set.

If the invited user does not have a Beemray user ID yet, they will be provided with a link to create one. Once created, they will be guided to confirm the account ownership.

If the invited user already has an account, they will receive an email notification of the new account ownership.

Audience

Beemray enables the building of audiences based on location, in-app behaviour, on-site behaviour, event attributes & other data. Each individual audience contains a set of rules. When a user fulfills the rule set of an audience, the user is placed within (or removed from) the audience in real-time. Honeypot Audience -section provides a UI to build and manage audiences.

An audience is the basis for all user profiling.
Once an audience is created and activated, it can’t be modified.

 

 

Creating an Audience

Name the audience with a unique name describing the context and content.
Audience name can’t be modified later on.

 

Choose Source(s)

– You can choose one or combine many web sources into one audience to define whether the traffic is to be included or excluded from an audience.
– Web source (Web SDK)
– Within each web source you can choose one or many events to be included in the audience being built. For more details, see Web Source (link)
– If you choose more than one event, the rule is always ‘OR’. So if the user generates any of the events, the user passes validation process going forward to the next step: location validation

 

Audience Editor - Source

 

Application Source (Mobile SDK)

Within each application source you can choose one or many events to be included in the audience being built. For more details, see Application Source (link)
If you choose more than one event, the rule is always ‘OR’. So if the user generates any of the events, the user passes validation process going forward to the next step: location validation.

 

Choose a Place Group

Defines where the user needs to be geographically located for them to fulfill an audience.
Place groups can include multiple places i.e. geographical areas.
You can only choose one place group per audience, but there are no limit to how many places are in a place group.

 

Audience Editor - Places

Beemray Audience Editor -Place Editor Map

 

Choose Stand elements

For every audience, you can configure conditional values from the Stand that need to be true for a user to fulfill an audience. A stand value can be a condition for an event to be true and the user must fulfill that condition for them to be included in that audience.
The Stand includes data that enriches the user profiling, such as user location-, behavioral- or interest data.

 

Choose Integrations

Defines to which integration partner (DMP) the fulfilled audience data is passed to.
One audience can be integrated into multiple integration partners (DMP).
Identified user is matched to an audience. All Beemray audiences that have been integrated with a partner, can be mapped against the corresponding audience ID in integration partner’s DMP
An audience that’s created within Beemray can also be passed to the DMP. Using this method, Beemray can add, remove, enable or disable audiences within the DMP.

 

Audience Editor - Integrations

 

Analytics

Beemray’s proprietary software facilitates real-time data collection, real-time location verification, real-time geolocation analytics, live heatmaps, and real-time audience output. All this from any location signal, via any internet connection, as a self serve SaaS platform. Data analysis can be interpreted from Beemray Honeypot interface, which provides meaningful insights and data visualisations to better understand user behavior and attribution.

To summarise – An audience consists of the following elements:

– Audience name
– Source(s)
– Places
– Stand
– Integrations (can include several 3rd party, one per each provider DMP)

Audience Accuracy as a Parameter

When creating a Beemray Audience, the admin might have a need to define which accuracies are taken into account in an Audience fulfilment. This is what we call Audience Accuracy as a Parameter.

This feature will enable an admin to build Audiences of desired accuracy for web users and for applications.

 

Mobile Application

When using a mobile application, at the time of installation, a location consent is requested from a user. If they give consent, we get extremely high location accuracy. In case they choose not to give consent, we’re unable to get any location data from them, and mobile application will not send any event data of a user.

 

Setting the Audience Accuracy

Audience Accuracy as a Parameter is set when creating an Audience. Audience accuracy is to be used only with Beemray Web Source, and only when a user has not given a location consent.

Predefined Audience Accuracy categories are: High, Medium and Low.

High = up to 500m

Medium = up to 5km

Low = up to 20 km

Any (Default) = up to 5 km

Anything over 20km will be excluded out from any Beemray Audiences.

The accuracy value chosen for an Audience will apply to all Places within the the Place Group that has been selected to an Audience.

Places

Beemray Honeypot Places

Place Groups and Places

For device location data to be meaningful, it has to be tied to a specific place. A Place is an area that consists of the exact lat/long and it’s specified metric radius. A Place Group is a set of Places.

To detect the user’s location, Beemray uses patent-pending location technology across mobile web. The sophisticated system is based on machine learning algorithms that constantly improve the accuracy of our global location database. Our platform analyzes location data from different connection types and methods of hundreds of millions devices every day, in real-time, and cross-utilizes data for tuning accuracies. We call this “Location Crowdsourcing”. It ensures that our customers can always rely on the up-to-date location data for engagement and targeting in mobile web.

Read more on location crowsourcing: https://documentation.beemray.com/#location-crowdsourcing

Places and place groups are the elements that determine whether the user fulfills an Audience from the location perspective. Each Audience can only contain one Place Group.

You can create and manage Place Groups and Places in the ‘GEO’’ section of the Beemray Honeypot interface. This view can also be accessed while creating an Audience.

 

Place Group

  • Title
  • Description
  • May contain several Places
  • May be associated with multiple Audiences

 

Place

  • Title
  • Area
    • Geographical location and it’s determined metric radius
  • Can only belong to one Place Group

 

If all other Web Source rules and conditions within the Audience are met, and the user is located within the radius specified in the Place, the user meets the criteria for Audience fulfillment. Each place fulfillment can count towards multiple Audiences, as each Place Group can be associated with multiple Audiences.

It is quite usual that a single place group contains overlapping places.

To determine which place will get the hit for individual event when each IP -based request (no location consent available) has accuracy instead of absolute location, we’ve resolved this as follows:

  1. Place which fully contains the client’s area will get the hit. If there are multiple places which are fully contained by client’s area, the area which centroid is the closest with the centroid of the client’s area will get the hit.
  2. If none of the places of the place group is not fully contained by the client’s area, the place to get the hit will be calculated by using percentual area match between client’s area and place’s total area. Place with the best match index will get the hit.

To avoid this calculation, the places within the place group should be defined side by side without any place area overlapping.

 

 

Once data from Places has been gathered, it can be viewed and analysed in the analytics section under ‘Geo’ with the Beemray Honeypot. Data can be broken down to individual Places.

Partner Integrations

Integrations enable partners to use Beemray’s data to enrich their understanding of the user behaviour.

Beemray collects massive amounts of real-time location- and user data, analyzes it and identifies the user behavioural patterns.

We send the data to external partner platforms (such as Lotame DMP or Google DFP) to enrichen their data with in order to provide a deeper understanding and thus better targeting possibilities and conversion rates.

Ad servers and Marketing platforms give our customers complete data portability, and enable them to make their audiences actionable in real time.

 

Creating Integrations

Integrations between platforms can be created using various methods.

All integrations are configured under the ‘Account’ settings in Beemray Honeypot:

Example for a single customer admin view:

Integration Title Partner Name Customer ID Integration Method
Sports@LTM Lotame 49A15Y Batch file
News@LTM Lotame 34159G Batch file
Sports@DFP Google DFP YXYZ153 Pixel Integration

 

Once created and configured, one can choose which integrations are to be used when building a Beemray Audience. Audience settings contain a section for Partner Integrations, and from a checkbox-menu one can choose the Integration Titles.

Please note that the Audience includes only the Integration options already configured in the Account settings.

One Audience can be integrated into multiple integration partners.

Based on Audience rules and fulfillments, data is triggered and sent to external partners.

Beemray will agree together with the customer and the partner the integration methods and the data distribution frequency.

Upon what the partner prefers, it is possible for Beemray to send only the data that has changed since the last export, or the total amount of collected all data.

All Beemray audiences that have been integrated with a partner, can be mapped against the corresponding audience ID in the integration partner’s platform.

 

Pixel Integration

Beemray platform collects audience fulfillment data. The audience fulfillment data is transmitted via a pixel to 3rd party systems. The pixel integration is a lightweight way to transfer data to 3rd party systems. Beemray’s SDK will automatically/dynamically fire the pixel with correct data when the audience is fulfilled on Beemray’s end, so no user action is needed.  The pixel will include the fulfilled audience identifier as path/query parameter which is identified in the 3rd party system to corresponding audience. Usually this is faster way to integrate than the batch file.

An example of a Pixel code:

<img src=”pixel url/param1;key=param2;” width=1 height=1 border=0/>

 

Batch file Integration

Beemray platform collects audience fulfillment data to an batch file. The file syntax is specified by the integrated system. The audience fulfillment batch file is

uploaded to the 3rd party systems e.g once in a day usually via SSH(SCP/SFTP) connection. The file upload protocol is also determined by the integrated system.

In comparison to the pixel integration, the batch file integration is not so resource intensive for the 3rd party systems and for the data source.

In general this is a more slower way to integrate; the file can be big and it takes time to process on the receiving end. The processing time of the batch file depends on the 3rd party systems and their limitations.

 

What are the benefits?

Beemray’s direct integrations with DMPs, DSPs, Ad servers and Marketing platforms give you complete data portability, and enable you to make your audiences instantly actionable.

We enable enterprise publishers & marketers with simple tools to build complex products with Location Science as a Service. Each integration partner enables for the customer to integrate to multiple data providers and their segments.

As a Beemray partner, you’ll benefit from Beemray’s transparent & verified data, are able to offer customers deeper insights and enriched data, as well to use it to create audiences based on more contextual web & app experiences.

As a customer, you’ll be able to gain an understanding of your audience and their behaviour, identify and optimise your target segments, deepen your consumer engagement with real-time personalised content and marketing automation in co-operation with Beemray and the integrated partners.

Push Notifications

Push notifications are notifications that can be sent to a user via web or app.
These are alert style messages that slide in at the top or bottom right hand corner of a desktop screen, depending on the operating system, or appear on a mobile device in a manner nearly identical to push notifications delivered from apps. Push notifications are delivered on a user’s desktop or mobile screen anytime they have their browser open — regardless of whether or not the user is on the website. The primary use of push notifications is the delivery of content instantly to users so that the context will be correct.

Push Notifications can be sent collectively to all devices that have ever fulfilled an audience in their lifetime.

Push Notification sending is available at the Push Notification in Beemray Honeypot UI.

Create and Send a Push Notification

Beemray Push Manager

Create a Push Notification

Push Notification building starts in the Push Notification UI in Beemray Honeypot.

  • Hit ‘Add new’-button to create a new notification.
  • Create notification content
    Compose a Notification by typing into the notification field. Styling is not supported, only plain text form.

    • Title of the Push Notification
      Max of 30 characters
    • Message (Body) of the push notification
      Max of 30 characters
  • Add deep link
    Add a deep link to the push message. The deep link opens up a website or app view. The deep link includes deep link field (web url, app view etc link)
    Please include the protocol in the deeplink. ie: https://www.google.com works, but www.google.com does not work.
  • Hit ‘Save’-button to save the Push Notification you created.
    Once the Notification is saved, it will get unique ID and a created date.

Send a push notification

  • Select an Audience
    Select the audience you want to send the push to. Available Audiences are listed in the Push Notification UI.
    Please remember that Notification needs to be set to ‘ON’ in the Audience settings in order to be able to send Push Notifications for the Audience.
  • Send Limit
    You can choose to limit the total number of sent push notifications, set a numeral value
  • Frequency Capping
  • You can set a frequency capping for the push notifications. Numeral value is set in days. The user then receives a new push notification only every set amount of days.
  • Hit ‘Send Now’-button
    Your Push Notification is sent to the selected Audience.

Please note: In case you wish to only build a Push Notification, and to send it later, the Push Notification can be saved. In this option Audience selection is not needed, it will be added on at the time of sending the Push Notification.

Web Push Notification

These notifications can only be sent to users who have subscribed for these notifications from a specific website. As these notifications are pushed to user’s device, users don’t have to be present on the specific website to receive these notifications.

Generic Restrictions

  • Supported browsers for web push notifications
    • Desktop
      • Firefox 44.0+, Chrome 42.0+, Opera 42.0+, MS Edge
      • Currently not supported: Safari, Internet Explorer
    • Mobile web
      • Chrome for Android 56+, Firefox for Android 48+
      • Currently not supported: iOs Safari, Opera Mobile, Internet Explorer
  • Web push notifications are only supported on HTTPS/TLS secured websites.
  • Web push notifications are not received if the browser is in a private browsing mode.
  • If a user on Google Chrome with Mac OSX is browsing in a full screen mode, no notification is displayed.

Service Worker Restrictions

A service worker is a static javascript file that a browser runs in the background, separate from a web page. It enables offline usage of web sites, push notifications and background syncing.

A javascript file that enables push notifications for a Service Worker needs to be loaded from the same origin.

NOTE – Customer needs to download the javascript file from the Honeypot Settings and copy it the to their web server. It should be copied into web server’s root directory.

Service Worker Prerequisites

The Beemray service worker javascript file must be installed to the web server’s root directory. The Beemray service worker javascript file must be accessible from your web server URL: https://www.domain.com/beemray-sw.js

NOTE – The Beemray service worker javascript file’s name (beemray-sw.js) must not be changed.

DOWNLOAD link for service worker javascript file. 

App Push Notification

Mobile applications including Beemray Application SDK are able to receive push messages initiated by Beemray. The first time the user runs the app, he or she will be asked to grant permission to show push notifications. Once this is granted, the app will receive notifications even when it’s not running or not in foreground. The only exception is when the user intentionally force-quits the app. In that case, notifications are blocked until the user manually starts the app again.

Prerequisites

App developers must thoroughly follow the push notifications section in the SDK integration instructions in order to configure push notification properly. These steps include configuring their own accounts at the 3rd-party push notification server (Apple’s APN or Google’s FCM) and providing some data to Beemray, as well as adding the necessary code to the app.

Restrictions

  • Push notifications are supported on iOS and Android devices, for the same versions where Beemray SDK is supported.
  • As mentioned before, push notifications will not arrive if user denied permission or force-quits the app.
  • In order to open an app view when the deep link is followed, your app must register a custom URI scheme which you should use in your deep links.

Analytics

The Analytics dashboard is a self-serve tool that provides you insights on your users and helps you make informed data driven business decisions.

You’ll get data from real­time geolocation and instrumentation based analytics to live heatmaps for customer movement attribution. Beemray Honeypot UI provides a complete picture of customer behaviour, and how they interact with your digital touchpoints.

 

Dashboard

Beemray Honeypot Dashboard

Selection of timeframes: Hourly/Daily/Monthly. All reports within the dashboard are displayed using the chosen timeframe.

Dashboard is always in the Account context, displaying all audiences (that have any fullfilments in them) included in the customer account.

  • Total audience fulfillments as a numeric value
    • Total audience fulfillments as a numeric value in the previous timeframe
  • Percentual value of the change compared to the previous period
  • Total amounts of
    • Audiences
    • Places
  • Top 10 Audiences against time as a graph
    • Top 10 Audiences against time as a graph in the previous timeframe
  • Top Audiences within the selected time frame as a pie chart
  • Total amount of audience fulfilments in the account against time as a graph
    • Total amount of audience fulfilments in the account against time as a graph in the previous timeframe

The dashboard also contains summary of all sent push notifications within the whole account:

  • Total sent
  • Total views
  • Total clicked
  • CTR% account average

They’re displayed as a graph over time, as well as numeral values.

Audience Analytics

Audience Analytics

Audience Analytics_2

Audience Analytics_map

Audience section provides you with detailed real-time insights on how your users perform, when and where they interact with your content. Audience summary displays total number of audiences, audience fulfillments and percentual change compared to the previous time period within the customer account. As a reminder, audience description is available for each individual audience.

A list of all active audiences is available to choose each audience for closer inspection.

Each audience has the following features available:

  • Total audience fulfillments as a numeric value
    • Total audience fulfillments as a numeric value in the previous timeframe
  • Percentual value of the change compared to the previous period
  • Total amount of audience fulfilments in the account against time as a graph
    • Total amount of audience fulfilments in the account against time as a graph in the previous timeframe
  • Total amount of places in the audience against time as a graph
  • Table of the selected audience percentual distribution by place %
  • A pie chart of selected audience by the place – Top 5

Push Analytics

Push Analytics

Push notification analytics is available in the Beemray’s Honeypot Push section.

  • Summary of the whole account’s notifications as numeral values (same as the Dashboard)
  • A list of all push notifications created to the account incl. sorting and search.
  • Push Notification data per selected Push Notification:
    • Sent
    • Views
    • Clicked
    • CTR%

They’re displayed as a graph over time, as well as numeral values.

Sent: The total number of times a push notification has been sent
Views: The total number of times a user has seen a push notification
Clicks: The total number of times a users has clicked on a push notification
CTR%: CTR = Clicks/Views (The percentage of people who click on the push notification after seeing it)

Heatmap

Beemray Honeypot Heatmap

 

The Heatmap displays all activity within the selected area in real time.
It provides a real-time view on where generic users are located when they interact with content on web or app.

The Heatmap contains the following functionalities:

  • Search function to zoom to a desired location on map.
    • In addition to locations, the search function can also be used to search etc. for specific brands on the map.
  • Potential audience reach tool to estimate the number of users within the selected area.
    • To get an estimation, select the ‘box icon’-button in the map to draw an area of your choice. You get a numeric estimation above the map.
    • You can also move the selected area to a different location on the map using the ‘hand’-tool. Potential reach value is updated accordingly.

Application SDK

The Beemray Application SDK contains the code necessary to integrate Beemray functionalities with your application. As an app developer, you just have to link to the library/framework provided by Beemray and include a few lines of code. The SDK works under the hood collecting anonymized location and contextual data and sending it to Beemray servers at regular intervals.

ANDROID SDK

Beemray SDK for Android is designed to work across all Android platforms with a minimum OS version of 4.1 (API level 16). It is distributed as an Android library contained in an Android Archive (AAR) file. JDK 8 is required and the latest version of Android Studio and Gradle plugin for Android is always recommended.

Android SDK Integration Instructions

Add Beemray’s Maven repository

We distribute Beemray SDK for Android via our own Maven repository. You can add it to your top-level build.gradle file with the following line:

Add Beemray SDK dependency

Go to your module’s build.gradle and link to Beemray SDK by adding one line to the dependencies section (changing the version number if necessary):

Additionally, in order to avoid version conflicts, set the compileOptions under the android section.

Finally, make sure that the value for minSdkVersion is at least 16, which is the lowest supported version.

Enable Push Notifications

Beemray SDK for Android makes use of Firebase Cloud Messaging (FCM) service to subscribe for push notifications.

Follow official instructions from Google to add Firebase to your app. You can do it manually or use the Assistant available in recent versions of Android Studio. Either way, only the first steps are necessary and you will end up with:

  • A google-services.json file for your app downloaded into your module folder.
  • A new dependency in your top-level build.gradle:
  • A new dependency in your module’s build.gradle (version number may differ):
  • A plugin applied at the end of your module’s build.gradle:

That’s all. You don’t need to create any service or add any code to AndroidManifest.xml; the SDK will do it for you.

REQUEST LOCATION PERMISSION (ANDROID 6+)

Version 6 of Android introduced runtime permissions. In order to use Android service, you need to ask the user to accept the ACCESS_FINE_LOCATION permission.

The official documentation explains how to request permissions at runtime. In short, you need to check if permission is granted before starting Beemray, and request it otherwise. You would normally do it in your main activity’s onCreate method.

First, define an int constant that you’ll use to identify this permission request.

Check if permission is granted or request it using the previously defined constant.

Additionally, override this method in your activity in order to detect when the user has accepted the permission.

For more details about requesting runtime permission, check the official documentation.

Start the Beemray service

Once you are granted fine location permission, you can start the Beemray with the following code block. Don’t forget to use your own API key provided by Beemray.

You are done! Run your app and Beemray SDK will start collecting data for you.

ADD A LISTENER FOR SERVICE STATUS

You can use a broadcast receiver to listen to changes in the Beemray service status.

You must register the receiver before you start the service:

Do not forget to unregister the receiver in order to avoid memory leaks. You can do it in your activity’s onDestroy  method:

ADD A LISTENER FOR SENT EVENTS

You can use a broadcast receiver to be notified when a event was sent successfully or failed to be sent. The receiver must be registered using an intent filter with action EventSender.ACTION_NEW_EVENT or, literally, com.beemray.intent.action.NEW-EVENT. The following is an example of such a receiver:

Register your receiver anywhere in your activity:

And don’t forget to unregister it when you no longer need it (or, ultimately, in your activity’s  onDestroy  method) in order to avoid memory leaks.

Alternatively, you can create a BroadcastReceiver  subclass and register it application-wide, that is, in your AndroidManifest.xml :

Intercept event delivery

Beemray SDK lets you define a callback class to run your own code during event delivery workflow. To begin with, create a class that implements com.beemray.android.Callback interface. This interface defines two methods:

The beforeSend  method lets you modify any event prior to delivery, or prevent delivery at all by returning false . As for  afterSend  method, note that it is an alternative way to using a broadcast receiver to be notified when an event is sent.

Finally, provide your class to the configuration object used to start Beemray. By doing so, you are telling Beemray to instantiate your class and use it as callback for every event delivery.

IOS SDK

Beemray SDK for iOS contains the code necessary to integrate Beemray functionalities with your application. This SDK is designed to work across all iOS platforms, with a minimum OS version of 8.0. It comes in the form of a static framework.

iOS Integration Instructions

Get the SDK

Download the latest Beemray SDK for iOS from our download site and unzip it.

Link against Beemray static framework

  1. Drag the Beemray.framework file from Finder into your project in Xcode’s Navigator pane. In the “Add to targets” section, select your main target. You can choose if you want to select “Copy items if needed”.
  2. If you did not select “Copy items if needed”, go to the Build Settings tab of your main target, look for the entry “Framework Search Paths” and set its value to the directory where the framework is located
  3. In the Build Settings tab of your app target, search for “Other Linker Flags”. Click the + button, and add a flag with text: -ObjC

Link against the required dynamic frameworks

Go to the Build Phases tab of your main target. You will see that Beemray.framework is already added to the “Link Binary With Libraries” section (if not, add it now). Add entries to this section for all the required frameworks and libraries. Required frameworks are:

  1. CoreBluetooth.framework
  2. CoreLocation.framework
  3. CoreTelephony.framework
  4. SystemConfiguration.framework
  5. libsqlite3.tbd

Optionally, link to AdSupport.framework. If this framework is linked (and the user has not limited ad tracking), the device’s advertising identifier is included in device information sent to Beemray server.

Provide a location usage description

Apple requires you to provide a message stating why you want to access user location. Beemray SDK needs “always” location permission, although it will work (very limited) with “when in use” permission.

Open your Info.plist file and add two new rows of type String with keys:

  • NSLocationAlwaysAndWhenInUseUsageDescription (“Privacy – Location Always and When In Use Usage Description”)
  • NSLocationWhenInUseUsageDescription (“Privacy – Location When In Use Usage Description”)
  • NSLocationAlwaysUsageDescription (“Privacy – Location Always Usage Description“), if your app supports iOS 10 and earlier)

As values, describe how your users will benefit from giving access to their location.

ENABLE PUSH NOTIFICATIONS IN YOUR APP

  1. At the Capabilities tab of your project, enable Push Notifications. Also enable Background Modes and select the “Remote notifications” checkbox.
  2. Follow Apple documentation and create an APNs authentication token signing key. Download your key as a file with .p8 file extension. Also write down your key ID.
  3. Contact our support team and, for each of your apps, provide your key ( .p8 file), key ID and bundle ID and team ID. A single key per app is enough to communicate with Sandbox and Production APN servers.

Add some code to your app delegate

You can normally start the Beemray service when your application is launched. In your application delegate (typically AppDelegate.m), add Beemray framework import to the imports section:

Add the following code to the application:didFinishLaunchingWithOptions method. The only required configuration parameter is your Beemray API key.

Note: You must include the line conf.development = YES when creating development builds. However, you must not include it in ad hoc or distribution builds.

Finally, add these methods to the application delegate:

Just one more step away. If you want to provide your own delegate to UNUserNotificationCenter, do it after starting Beemray service, and call these methods from your own delegate:

You are done! Run your app and Beemray SDK will start collecting data for you.

Adjust logging level

Optionally, you can adjust Beemray SDK logging level by setting the following properties:

Using a delegate to catch SDK events

Optionally, you can set an object implementing  BeemrayDelegate  protocol as a delegate for the SDK.

This protocol defines the following methods, which are all optional:

WEB SDK

Web SDK contains the Javascript code necessary to integrate Beemray functionalities with your website. This SDK is designed to work across all browsers. The Web SDK works by including just a block of Javascript code to a website.

Prerequisite: You need to make sure that your website can communicate with the Beemray Web SDK. To do it you need to configure a pageurl in the Honeypot UI.

INTEGRATION

Loads the Beemray Web SDK library. Query parameter ‘source’ must exist and the parameter value must be Base64 encoded.
Simple example how to load Web SDK without loader script:

NOTE! APIKEY should be replaced with your own API key which can be found on Beemray Admin when you login.

BROWSER SUPPORT

The Web SDK is a standards-compliant Javascript library, and is built to support a wide array of browser environments. That said, there are a few older browsers which are known to not work as expected. The following browsers are fully supported by the Web SDK.

  • Internet Explorer 10 and newer
  • Opera 12 and newer
  • Android Browser 4 and newer
  • Safari 6 and newer
  • Firefox 11 and newer
  • Google Chrome 18 and newer
  • Microsoft Edge

DFP key-value targeting

Beemray audiences can be used in DFP key-value targeting. You can use the Beemray Audience information, the Place information or the Stand values when a respective event response is available. It is always recommended to use JS code to generate the targeting tags.

The best way to use Beemray data in targeting is to send a custom event when the targeting tag is being processed on the page. You need to define a custom event using the Honeypot admin and use the same event name in the custom event on the page. More on custom events here: Web events

The event response contains all the information for the device at the time. We recommend that you use a timeout when sending the event to make sure that the event sending is not blocking the tag processing too much. You’re able to choose and define which values of the response you’d like to use in your targeting tag.
Event response instructions here: Web events

We recommend that you use identifiers as a values whenever the information is available. The identifiers are set automatically in the Beemray backend and the format is always the same.

Titles are set by the admin user in Beemray Honeypot and they might vary in format, thus making them not the most optimal choice to be used in key-value targeting.

Event API

Custom Event

Beemray’s SDK EventAPI provides functionalities to send custom events to Beemray platform.

Custom events are built using the Beemray EventAPI and are inserted directly to web site source code by the customer.
They are not managed via the Honeypot UI,  Honeypot UI only includes an option for the admin to choose those custom events as web source rules once the custom event scripts are in place on site. 

In order for a Beemray audience to be fulfilled, the custom event needs to be set as a web source rule and the custom event script needs to be on site. 

Example 1:

  • Use case: Target an audience that is working in the London City and is currently at the office (location=City, state=work, when=now).
  • Integration: Integrate Beemray with Google DFP using key value pairs.
  • Benefit: Realtime advertising targeting for people at the office during lunch hours.

Web

Prerequisites

  • The Beemray Web SDK must be loaded on the host website.

Using the Event API

 

Creating an Event

This creates new Event which can be sent to Beemray backend services.

The eventTitle is the title of the sent Event and the endpointUrl is the location of the Beemray backend API where the Event is sent. The endPointUrl should always be “/rest/event/web/plain”.

 

Sending Event to backend services

The created Event can be sent by calling the send(callback) function with callback function as parameter.

 

Sending Event to backend services with timeout

The created Event can be sent by calling the send(callback, timeout) function with callback function and timeout as parameter. The timeout parameter representing the number of milliseconds a request can take before automatically being terminated and the callback executed. The default value is 0, which means there is no timeout.

 

Event Response

The response from backend services which contains the information about the Audiences. The response is available as first parameter of the given callback.

The response is an AudienceFulfillPlainResponse JavaScript Object.

 

Example Event sending with response handling

Example Event sending with request timeout with response handling

Example Event sending with check that Beemray Web SDK loaded and ready to be used


Example Event response Object in JSON format


AudienceFulfillPlainResponse Object properties

property description type
list Contains the information about the Audiences. Array


AudiencePlainMatch Object properties

property description type
id Unique identifier of the entity which identifies the entity on Beemray’s services. Number
title Title of the entity. String
place Place which was used on Audience. Object
source Source which was used on Audience. Object

UserPlaceInfo Object properties

The UserPlaceInfo contains formation about the client’s location data, including personal places.

This information isn’t sent until the client fulfils certain conditions: the client must have visited the pages containing the WebSDKs during several days and several hours.

property description type
clientId The ID of the client. String
state The state of the current place. At the moment, HOME and WORK states are implemented.

The state is set when the client is 150 metres or closer to home or work.

Array
personalPlaces The list of the personal places (max 7). Array

PersonalPlaceInfo Object properties

The PersonalPlaceInfo contains information about the most visited places (1 to 7 places). One of them is automatically selected as HOME and another one of them is automatically selected as WORK.

property description type
accuracy The GPS accuracy (in metres) measured for this place. Number
distanceTo The distance (in metres) from the current place to this place. Number
featured The state of this place. HOME: the place is home. WORK: the place is WORK. String
hits The number of visits (i.e. page loads) in or near this place. (150 metres or closer). Number
lastVisit The latest visit to this place (as a Unix timestamp). Number
lat The GPS latitude of the place. Number
lon The GPS longitude of the place. Array

RELEASE NOTES

WEB SDK

7.1.0 (15.12.2017)

– Client Integrations Support.
– Web SDK now in plain ES5 instead of ES6.
– Loader process, to allow the Web SDK to be loaded asynchronous fashion.
– New Event API to support custom event sending more easier way.

5.1.0 (24.2.2017)
– Web notification support

5.0.0 (04.10.2016)
– New Tag Manager support
– Ability to include any number of scripts

IOS SDK

7.5.1 (13.3.2018)
– New delegate method willSendEvent

7.4.0 (21.2.2018)
– Full support for multiple apps per account
– Send analytics about viewed/clicked push notifications
– Add error  argument to delegate’s didSendEvent:withResponse
– Fix bug that might result in app crash
– Fix bug that prevented building for old simulators

7.2.0 (22.12.2017)
– Improved event behaviour

7.1.0 (15.12.2017)
– Google DFP integration
– Push notification support is now optional
– Track when push notifications are received/open
– Detect user home & work
– Keep a history of fulfilled audiences over time
– Several minor bug fixes

5.1.0 (14.03.2017)
– combine adjacent places.
– send visited places data to backend regularly
– use areas of 0.0005 degrees
– minor bug fixes and performance improvements

5.0.1 (25.11.2016)
– gather more info about the device: wifi status, speed and direction

5.0.0 (06.10.2016)
– beems are excluded from the core SDK.
– battery-saving improvements. Removal of the background location mode.
– keep track of most visited places.

3.1.1 (15.05.2016)
– more reliable beem reception
– show date of arrival for beems in beembox

3.1.0 (04.04.2016)
– more accurate location tracking (uses location background mode)
– battery-saving improvements
– add support for external device ID’s

3.0.0 (13.02.2016)
– totally revamped UI
– fully customizable UI
– local image cachev

2.4.9 (11.12.2015)
– improve performance & battery saving on location updates

2.4.8 (10.12.2015)
– add deep-link support
– simplify service startup & configuration (check the documentation!)

2.4.7 (13.11.2015)
– UI changes in beem box and beem view
– ensure compatibility with other push notifications not sent by Beemray
– make persistent notification optional
– fixes in notification behavior: in-app banner, badge number and notification tap
– add app life cycle events
– prevent warnings caused by implicit properties attributes

2.4.4 (05.10.2015)
– fixed some integration issues with iOS 7.1

2.4.2 (21.09.2015)
– updated look & feel
– add method to save a single profile element
– gather carrier information

2.3.1 (05.06.2015)
– improved beem flow
– improved profile management

2.3.0 (06.05.2015)
– beacon support
– custom event support

2.2.0 (18.03.2015)
– new notification handling
– new action bar element design
– more efficient battery consumption management

ANDROID SDK

7.4.0 (13.3.2018)
– New callback system for event delivery
– Internal improvements and clean up of unused code

7.3.1 (21.2.2018)
– Send analytics about viewed/clicked push notifications
– Make use of notification channel (required in Android O)
– Fix bug causing app crash when deep link was invalid or missing

7.2.0 (21.12.2017)
– Adapt to Android 8 background execution and location restrictions
– Improved event behaviour

7.1.0 (15.12.2017)
– Google DFP integration
– Push notification support is now optional
– Track when push notifications are received/open
– Detect user home & work
– Keep a history of fulfilled audiences over time
– Several minor bug fixes

5.1.0 (14.03.2017)
– combine adjacent places.
– send visited places data to backend regularly
– use areas of 0.0005 degrees
– restart Beemray service after device is rebooted

5.0.1 (25.11.2016)
– gather more info about the device: wifi status, speed and direction

5.0.0 (07.10.2016)
– beems are excluded from the core SDK.
– keep track of most visited places.

3.0.2 (15.05.2016)
– bug-fixing release.

3.0.1 (15.04.2016)
– adapt to Android 6 runtime permissions. Drop requirement of some permissions.
– use latest version of Play Services (8.4.0)
– avoid exception when closing empty Beembox.
– avoid exception when Bluetooth is not enabled.

3.0.0 (17.03.2016)
– totally revamped UI
– local image cache
– custom notification icons
– richer information from device

2.4.6 (14.12.2015)
– add deep-link support
– improve behavior of non-persistent notifications

2.4.5 (18.11.2015)
– add compatibility with Parse.com push notifications
– bug fixing

2.4.4 (30.10.2015)
– improved push notifications integration
– minor UI changes

2.4.2 (28.09.2015)
– updated service start mechanism
– beacon service now follows Bluetooth service life cycle
– improvements in statistics

2.3.0 (22.07.2015)
– a general beacon support
– improved event API
– minor bug fixes
– minor changes to improve the battery life

2.2.0 (15.03.2015)
– push notification improvements
– lot of layout changes
– brand new beembox view
– location service improvements
– some new icons

2.0.0 (01.02.2015)
– additional language support (pt, fr, it)
– improved battery consumption

HONEYPOT

6.44 (05.04.2017)
– flickering & misplaced tooltip bug fix for charts
– disable line charts when only one data row
– update configurable options on pageURL

6.41 (03.04.2017)
– CPC to CTR in push analytics
– Firefox bug fix for activity map
– loader & empty data handlers for all analytic info tables and summaries
– minor text updates & unifying
– restructuring analytics charts & new top cities pie chart
– chart legend pagination bug fix

6.35 (06.03.2017)
– active list item indicator is now part of list components functionality
– removed background from body + smaller font size for inputs
– “SDK” is renamed to “Linking” in settings
– copy to clipboard buttons for Api key & Web SDK script in settings
– push notification script for settings- unifying terms, menus and titles
– new version of activity map in labs

6.27 (24.02.2017)
– bug fix: binding list item selection to chart when both are empty
– push analytics title + menu term updates
– dynamic reach calculation for push campaign creator
– more infotable values for push campaign analytics
– ‘Devices’ analytics is now ‘Places’ analytics
– geo chart component
– Countries map for replacing old country chart in Places analytics

6.20 (23.02.2017)
– fail safe functionality for getting current location in maps
– localized number format for info and summary tables
– Push notification manager for labs (BETA)
– Push campaign analytics (BETA)

6.16 (20.02.2017)
– audience heatmap bug fix

6.15 (20.02.2017)
– improved functionality for audience heat maps
– real radius indicator for accuracy map
– minor styles text update
– blacklisted locations map for labs

6.10 (14.02.2017)

– clear main context on login
– dynamic pop-up title for place manager
– paired list component
– loader icon for save buttons
– first login autofill issue fix
– updated content loader gfx
– slidable view for map tools
– places list for place manager
– date picker component
– “maxlength” attribute support for custom input
– prevent preview refresh & list re-select after save
– fix cropped loader image in list
– multiselect list component
– global Set intersection & Set difference functions
– heatmap update for Audience analytics
– accuracy map for labs
– Hot places by devices for labs
– bounding box & zoom for map instructions
– accuracy map for labs
– map overlay component
– shapes for heatmap
– improved loader for maps
– improved html structure for maps
– minor text updates for analytics
– improved “fullscreen” functionality for map

5.81 (23.01.2017)
– use encodeURIComponent for verifyexistence uris
– bug fix for error handling when adding places to audience
– clear all appended errors onSuccess when using verifyexistence
– update for audience analytics instructions
– set map center based to existing places if available
– allow place remove only in editor mode
– updated colors in place editor
– keep current place group in editor when saving first time

5.72 (20.01.2017)
– new default date range & resolution for charts

5.71 (18.01.2017)
– incorrect initial set center function bug fix for maps
– better indicator for selected place in editor
– new versions of map & overlay for audience analytics
– clear charts before reuse
– infinite loading bug fix for empty lists
– remove saturation & devices charts from audiences
– minor text updates

5.63 (09.01.2017)
– fix for heat map not cleaning properly when clicking fast
– prevent creating new map if there is already one
– used data points view in dashboard
– calendar icon for charts
– total fulfillments chart for audiences
– loader for list
– functionality to reselect list item remotely
– popup dialog component
– draggability for pop up
– places manager
– implemented new core version for places
– better flow for list reference
– zoom/expand map functionality
– number formatting function for charts
– disable time picker in charts when using wider than one day date range, otherwise show time picker
– change resolution to 60 if date range is less than 24 hours, restore the original one if going back to wider range
– change chart resolution dynamically based to date range
– drag to zoom functionality to charts
– reset zoom in charts with mouse right click
– fixed loader bug in charts when data is null
– add loader when refreshing
– all charts are now zoomable
– dynamic x-axis labels based to resolution
– standalone datamodel to preview component
– separated refresh list function to preview component
– preview component: handle empty instructions text container error on cleanStates()
– touchpoints
– application manager
– literal format for x-axis labels for charts
– center map based to bounds of weighted data

5.35 (11.11.2016)
– added loader icon to audience save
– chart title updates
– fixed map loading bug when empty data
– 2 weeks insted of 1 month default range for charts
– descriptions for charts
– summary for audience analytcs
– error message for empty chart data
– confirmation dialog
– audience heatmap polling & clearing bugfix
– clean more on logout
– enable audience reach analytics
– better set center method for heatmaps

5.23 (24.10.2016)
– temp fix for heat maps intervals bug after moving another page
– missing Event @class property bug fix
– another infinite loop in PageUrl list bug fixed

5.20 (10.10.2016)
– better contrast for man made objects in location rule maps
– audience rules preview places zoom button remake and generic toggle element functionality
– double edititem bugfix
– list / preview flow remake
– load items data individually when selected
– reduced list data weight
– new colors to charts
– demo heat map for labs
– fixed audience rules preview bug
– updated event rules Event class structure for new list/selected item flow
– removed automatic place description filling based to location because of instability
– added beemray loader gif

5.10 (03.10.2016)
– new audience structure implementation
– fixed audience preview places not shown bug
– visual improvements
– allow login submit with enter keypress
– footer element
– text content corrections
– new “saturation” and “users” charts for audience
– cities over time chart for devices analytics
– fixed inaccurace places bug in audiences location rulebuilder
– applicable input field for slider component
– more colors for google charts Beemray base styles
– web sdk script for clients to copy

3.1.2 (02.05.2016)
– more accurate location on major cities
– support for INAREA/ENTER/EXIT events for beacon actions – Minor bug fixes

3.1.1 (22.02.2016)
– fully configurable consent overlay added for geolocation agreement on Web SDK
– negation operator (NOT) added for segment building
– time intervals supported on segment building – Minor bug fixes

3.1 (15.02.2016)
– machine learning algorithms added
– structured segmentation with nested operators (AND/OR)
– support to register external CRM customer IDs with Beemray’s device id
– support to use “once an hour” and “once a minute” rules on beem’s frequency
– minor bug fixes

3.0.6 (01.02.2016)
– rest API documentation added
– spot API updated
– weight API updated
– segment API updated
– analytics API updated
– fixed a bug where expired iOS certificates on customer’s account was dropping the server connection when trying to send push notifications to iOS devices
– minor bug fixes

3.0.5 (25.01.2016)
– event elements can be mapped as aggregative profile elements with adjusted weights by WeightAPI
– weights for segment elements can be configured by WeightAPI
– ranking the devices within a segment based on behaviour
– database keep track if device has bluetooth and/or location services enabled
– minor bug fixes

3.0.4 (18.01.2016)
– minor bug fixes

3.0.3 (11.01.2016)
– tag containers for WebSDK
– support for multiple beems on same page on WebSDK
– support to send beems by tag container with configurable tag rules
– weightAPI to set priorities to each segment attribute for better insights
– partial matching on segmentation
– minor bug fixes

3.0.2 (16.12.2015)
– high performance heatmap with new cache layer
– synchronous loading of websdk
– preview for web beem
– increased maximum range on spot distance
– minor bug fixes

3.0.1 (23.11.2015)
– default resolution on analytics changed
– performance fixes on profile’s number element types
– page configuration to match browser urls with regular expressions on websdk
– minor bugs fixed

3.0 (16.11.2015)
– self service account creation added
– event management added
– datapoint usage on events added
– fixed bug on event elements configuration as segment elements
– minor bugs fixed

2.7 (30.10.2015)
– support for web beems added
– added support to build rules by user web behaviour
– page analytics added
– minor bugs fixed

2.6 (08.10.2015)
– beacon analytics added
– page management for web beems added
– deeplinking on beems
– improvements on heat map accuracy
– simplified rules
– performance tweaks on DB
– minor bugs fixed

2.5.1 (27.09.2015)
– enhanced data sharding on beacons, devices and rules.
– more accurate beem delivery for beacons
– beacons got new action: INAREA
– minor bugs fixed

2.5.0 (21.09.2015)
– enhanced UI
– refactor on profile’s structure
– segmentAPI added
– timestampElement added into event attributes
– carrierInfo added into device requests
– support for multiple users in single account
– refactor on WebSDK’s core
– support for HTTP/GET on EventAPI
– more logic added to keep data shards balanced over the environment
– minor bugs fixed

2.4.0 (01.07.2015)
– added Spot statistics

2.3.3 (09.05.2015)
– improvements on EventAPI

2.3.2 (08.05.2015)
– unique apps statistic added to analytics heat map view
– search location by address added to analytics heat map view
– improved profile management

2.3.0 (25.05.2015)
– enhanced UI for creating and modifying profiles

2.2.0 (20.03.2015)
– map-based analytics view
– profile certificate uploads (test and production) for iOS
– improved beem templates

DOWNLOADS

WEB SDK

Login to your Beemray account and copy the Web SDK from the Settings section of the Honeypot UI.

IOS SDK

Click below to download the latest version of Beemray SDK for iOS.

beemray-ios-sdk-7.5.1.zip |  Release date 13/3/2018

ANDROID SDK

We recommend adding Beemray SDK for Android as a Gradle dependency:

com.beemray:android-sdk:7.4.0

from Beemray’s Maven repository:

https://dl.beemray.com/maven/

If you still prefer to download it manually, click the link below (note that you will have to handle dependencies yourself).

android-sdk-7.4.0.aar |  Release date 13/3/2018

BEEMRAY VIEWER

Beemray Honeypot Viewer is a demo application that enables you to test location tracking and place settings on your account.

AppStore

google-play

 

 

 

Contact our developers

Glossary

Audience Audience is a subset of devices which fulfill the specified attributes for a particular audience. Each individual audience contains one-to-many attributes based on user behaviour. Audiences are a great way to easily analyse and target the desired customers. Beemray enables to build audiences using algorithms based on location, events, time.
Beacon Beacon is a bluetooth wireless device transmitting a continuous radio signal which is detected by nearby smart devices. Beacons can be used as touchpoints when building audiences.
Campaign Beemray enables to build web-based push notification campaigns to reach audiences real-time. Push notification campaigns are a one-way communication channel towards the end-users, without them having to interact.
Check-in Check-in is a workshop managed by a Beemray certified specialist. The outcome of the check-in is a report containing the current customer status, concrete targets for implementing Beemray, a checklist of required configurations, recommendations for audiences to be built and necessary data events to start with.
CTR% CTR = Clicks/Views. The percentage of people who click on the push notification after seeing it
Current Reach Once the audience is created and selected for a push notification campaign, an estimation of the target audience size is provided by Beemray.
Device Device is a physical device like a mobile phone, tablet, computer etc. We can track the location of the device and its behaviour based on events either inside applications or on websites.
Event An event is a user interaction with content that can be tracked independently from a web page or mobile application. Example: Button clicks, page views or anything clickable are all examples of actions that are tracked as Events.
Fulfilment When a device fulfills audience rules, it is counted as a fulfillment.
Honeypot Online interface for Beemray audience intelligence platform that enables data analysis, gaining insights and audience building capabilities.
Id Each entity related to platform gets a unique ID generated by Beemray.
Location accuracy Presents geolocation accuracy in a specific geolocation point.
Location Services Location services are a part of iOS and Android device operating systems to keep track of a user location, using background or foreground modes.
Phone Support Phone support is provided during office hours. The support helps with integration, development, system administration etc tasks online at support.beemray.com
Place A place is a named geographical location. For device location data to be meaningful, it has to be tied to a specific place.
Priority Feature A priority feature is a planned road-map feature and its development has been expedited based on customer request.
Push Notification Push notifications are used in web-based push notification campaigns to reach audiences real-time. A push notification is a pop up message towards the end-users, without them having to interact.
SDK SDK is added to the website or application to collect data (events, location etc). This data is utilised for audience building and analysis. Beemray SDKs support common web browsers, iOS & Android mobile devices and beacons.
Timeout Representing the maximum length of time (in seconds) the device is allowed to take in order to return a position.
Training Training session includes Beemray platform basics, configuration and administration workflow. Max 8 hrs onsite training and travel costs are to be added.
User behaviour User behaviour is a flow of actions of a user in a particular situation. To track and understand customer behaviour, we collect device data, online events and location data. The collected data is interpreted by Beemray platform to generate metrics, insights and to build audiences.
Views The number of times a user has seen a push notification.
Suggest Edit