Braze
Using Factual Location Engine with Braze
Factual provides an integration between the Factual Engine SDK and Braze's Mobile SDK to help better understand users in the physical world and build personalized experiences driving user engagement and revenue.
Please see the Github project for detailed integration instructions
Use Cases
- Personalize user experience
- Retail/QSR: limited time offers messaging (send app users a push notification when they are within an X mile radius of a specific location for a given specific time frame), drive user to store
- Finance: fraud detection, budget management, loan up-sell
- Travel/News: contextual messaging/content.
- Create Location Based Audience and segments
- Group users into segments such as: sports enthusiasts, business travelers, frequent shoppers, fast food lovers based on their location patterns.
- Enrich user profiles
- Add location behavior and history to existing user profiles.
Release Notes
Version | Changes |
---|---|
1.0.0 | Initial release. Tracks circumstances from Factual Engine and sends the relevant data to Braze. |
1.1.0 | Sends each visited place from Factual Engine to Braze. |
1.2.0 | Compatible with Factual Engine SDK 8.4.0 |
1.4.0 | Specified dependencies for Factual Engine |
2.0.0 | Sends User Journey Span data and Engine Circumstance Near Places from Factual Engine to Braze. Reconfigured event names. Compatible with FactualEngineSDK 10. |
2.1.0 | Sends tags to Braze. Compatible with FactualEngineSDK 11+ |
Custom Events
Braze Engine sends Factual Engine SDK's events to Braze as custom events. Custom Events let you track user activities tying them back to corresponding digital engagement campaigns.
Event Name: engine_ + CIRCUMSTANCE_NAME
(CIRCUMSTANCE_NAME is the circumstance name as defined in the Factual Engine Dashboard or when programmatically creating a circumstance)
Description: Sent when a circumstance is met
property | type | description |
---|---|---|
incidence_id | String | Unique identifier for this circumstance |
event_source | String | Always factual |
tags | String | Tags associated with the circumstance |
user_latitude | Number / Double | Latitude of the user when the circumstance occurred |
user_longitude | Number / Double | Longitude of the user when the circumstance occurred |
Event Names: engine_at_ + CIRCUMSTANCE_NAME
and engine_near_ + CIRCUMSTANCE_NAME
Description: Places the user was at and/ or near which triggered the engine_ + CIRCUMSTANCE_NAME
event.
property | type | description |
---|---|---|
incidence_id | String | Unique identifier for this circumstance |
event_source | String | Always factual |
tags | String | Tags associated with the circumstance |
name | String | Name of the place |
factual_id | String | Factual's unique identifier for this place |
chain_name | String | Business chain of this place |
category_labels | String | Categories this place falls under |
user_latitude | Number / Double | Latitude of the user when the circumstance occurred |
user_longitude | Number / Double | Longitude of the user when the circumstance occurred |
latitude | Number / Double | Latitude coordinate of this place |
longitude | Number / Double | Longitude coordinate of this place |
Event Names: engine_span_occurred
Description: Sent each time a user journey span occurs
property | type | description |
---|---|---|
span_id | String | Unique identifier for this span |
event_source | String | Always factual |
country | String | Country where the span occurred |
postcode | String | Postcode where the span occurred |
localities | String | Localities where the span occurred |
region | String | Regions where the span occurred |
is_home | Bool | True if user is detected to be home |
is_work | Bool | True if user is detected to be at work |
start_time_unavailable | Bool | True if start time is unavailable |
end_time_unavailable | Bool | True if end time is unavailable |
start_timestamp | Number / Double | Timestamp of when user arrived here in Unix time |
end_timestamp | Number / Double | Timestamp of when user left here in Unix time |
duration | Number / Double | Length of time user was here in milliseconds (0.0 if start or end times are unavailable) |
ingress_latitude | Number / Double | Latitude coordinate of the ingress |
ingress_longitude | Number / Double | Longitude coordinate of the ingress |
Event Names: engine_span_attached_place
Description: Sent for each attached place in a user journey span
property | type | description |
---|---|---|
span_id | String | Unique identifier for this span |
event_source | String | Always factual |
name | String | Name of the place |
factual_id | String | Factual's unique identifier for this place |
country | String | The country of the place |
postcode | String | The postcode of the place |
locality | String | The locality of the place |
region | String | The region of the place |
chain_name | String | Business chain of this place |
category_labels | String | Categories this place falls under |
latitude | Number / Double | Latitude coordinate of this place |
longitude | Number / Double | Longitude coordinate of this place |
distance | Number / Double | Approximate distance between user and place in meters |
Example
For this example, we'll send a push notification whenever a user is near a coffee shop. This example assumes that the integration is installed successfully on iOS or Android and is done using the iOS or Android example application.
(1) Create a circumstance in the Engine Dashboard
The first step is to create a custom circumstance in the Engine Dashboard. Circumstances allow you to create personalized experiences and gain valuable insights about your users. Here, we'll set up a circumstance to notify the SDK when a user is near a coffee shop. Engine uses a machine learning based system for “attaching” devices to Factual places probabilistically.
Start by clicking Create New Campaign +
Enter your campaign name and add the tag push-to-braze
Click Next to Configure your circumstance.
Select At and select Categories
on the SELECT drop-down. On the ANY OF drop-down search for "Coffee" and select Cafe, Coffee and Tea Houses
.
Click Next to alter the duration of your campaign. You may leave this section unchanged.
Click Next to review your campaign and Launch to go live.
Now your circumstance will be triggered anytime the user is near a coffee shop.
(2) Add and configure your app in the Braze Dashboard
In the Braze Dashboard go to the Manage App Group tab under the App Settings section and add your app there. Also, be sure to setup your Push Notification Settings.
Then, select the tab Custom Events
and select the button Add Custom Events
Enter the event name engine_near_ + CIRCUMSTANCE_NAME
. As shown above, when creating this circumstance in the Engine Dashboard, we named our circumstance coffee-shop
; so for this example, your event name will be engine_near_coffee-shop
.
For this example, we will only track Engine Circumstance Near Place events, but If you wish to add circumstance events tracking you can add the event name engine_ + CIRCUMSTANCE_NAME
and for At Place events tracking you can add the event name engine_at_ + CIRCUMSTANCE_NAME
. For User Journey Spans add engine_span_occurred
and for places attached to the User Journey Span add engine_span_attached_place
.
The properties for these events on Braze will be filled automatically when we first send an event.
(3) Setup a push notification in the Braze Dashboard
Now, create a new Campaign in the Campaigns tab under the Engagement section by pressing on the Create Campaign
button and selecting Push Notification
.
Follow the given steps in creating the push notification:
- 1. Compose
Compose your push notification any way you like. To see the name of the place that triggered the circumstance, add {{event_properties.${name}}} to the notification. For example, in the message you can use You are near {{event_properties.${{name}}}}.
and if the user is near a Coffee Bean they will see You are near Coffee Bean.
Note: some locations have long names and may result in truncated message titles.
- 2. Delivery
Select Action-Based Delivery
and for the Trigger Action
select Perform Custom Event
then press Add Trigger
. In the Perform Custom Event
drop-down, select the custom event we added earlier engine_near_ + CIRCUMSTANCE_NAME
.
Under Schedule Delay set Once trigger event occurs, send campaign to immediately
.
Under Campaign Duration configure the duration of the campaign to run however you like.
Under Delivery Controls be sure to select Allow users to become re-eligible to receive campaign
if you want to receive the notification more than once.
- 3. Target Users
Click Add Segment and select All Users
for your app. For this test, be sure to not limit the number of people who will receive the campaign or the rate at which the campaign will send to ensure the campaign is working properly.
Under Distribute Users Among Variants set the Control Group to 0% and Variant 1 to 100%. This will ensure everyone receives the example push notification.
- 4. Conversions
For this example, you may skip through this step.
- 5. Confirm
Review your information and select Launch Campaign
and you are done!
Once your automation is deployed, Engine will send a custom event, in real-time, when a device triggers the coffee-shop
circumstance. From there, Braze takes over and delivers the push notification.
Updated 4 months ago