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

VersionChanges
1.0.0Initial release. Tracks circumstances from Factual Engine and sends the relevant data to Braze.
1.1.0Sends each visited place from Factual Engine to Braze.
1.2.0Compatible with Factual Engine SDK 8.4.0
1.4.0Specified dependencies for Factual Engine
2.0.0Sends User Journey Span data and Engine Circumstance Near Places from Factual Engine to Braze. Reconfigured event names. Compatible with FactualEngineSDK 10.
2.1.0Sends 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

propertytypedescription
incidence_idStringUnique identifier for this circumstance
event_sourceStringAlways factual
tagsStringTags associated with the circumstance
user_latitudeNumber / DoubleLatitude of the user when the circumstance occurred
user_longitudeNumber / DoubleLongitude 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.

propertytypedescription
incidence_idStringUnique identifier for this circumstance
event_sourceStringAlways factual
tagsStringTags associated with the circumstance
nameStringName of the place
factual_idStringFactual's unique identifier for this place
chain_nameStringBusiness chain of this place
category_labelsStringCategories this place falls under
user_latitudeNumber / DoubleLatitude of the user when the circumstance occurred
user_longitudeNumber / DoubleLongitude of the user when the circumstance occurred
latitudeNumber / DoubleLatitude coordinate of this place
longitudeNumber / DoubleLongitude coordinate of this place

Event Names: engine_span_occurred

Description: Sent each time a user journey span occurs

propertytypedescription
span_idStringUnique identifier for this span
event_sourceStringAlways factual
countryStringCountry where the span occurred
postcodeStringPostcode where the span occurred
localitiesStringLocalities where the span occurred
regionStringRegions where the span occurred
is_homeBoolTrue if user is detected to be home
is_workBoolTrue if user is detected to be at work
start_time_unavailableBoolTrue if start time is unavailable
end_time_unavailableBoolTrue if end time is unavailable
start_timestampNumber / DoubleTimestamp of when user arrived here in Unix time
end_timestampNumber / DoubleTimestamp of when user left here in Unix time
durationNumber / DoubleLength of time user was here in milliseconds (0.0 if start or end times are unavailable)
ingress_latitudeNumber / DoubleLatitude coordinate of the ingress
ingress_longitudeNumber / DoubleLongitude coordinate of the ingress

Event Names: engine_span_attached_place

Description: Sent for each attached place in a user journey span

propertytypedescription
span_idStringUnique identifier for this span
event_sourceStringAlways factual
nameStringName of the place
factual_idStringFactual's unique identifier for this place
countryStringThe country of the place
postcodeStringThe postcode of the place
localityStringThe locality of the place
regionStringThe region of the place
chain_nameStringBusiness chain of this place
category_labelsStringCategories this place falls under
latitudeNumber / DoubleLatitude coordinate of this place
longitudeNumber / DoubleLongitude coordinate of this place
distanceNumber / DoubleApproximate 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

1884

Setup Circumstance

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.

1885

Configure Circumstance

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.

1875

Review Circumstance

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

1663

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.

532

Create Campaign

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.

1332

Compose Message

- 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.

343

Notification