Factual Integration

Factual is a location data company powering innovation in product development, mobile marketing, and real-world analytics.

Leverage Factual to better understand and uplevel mobile experiences through location data. Obtain a comprehensive picture of your customers’ online interests and behaviors with Factual’s Engine SDK and gain greater insight on end-user journeys and places visited. With this integration, available for both iOS and Android, developers are able to implement location intelligence and build personalized user engagement. This can by made possible by allowing Braze to receive custom events when the user is at a known Factual place or when an engine circumstance with the actionId push-to-braze is met.

Pre-Requisites

Requirement Origin Description
Engine SDK Factual Engine SDK In order to successfully integrate Factual’s Engine SDK with Braze, ensure the Engine client has been configured properly and starts successfully. This requires confirming an api key has been acquired and the Engine SDK has been properly imported into the project.
Appboy Client Braze SDK iOS Setup Also ensure the Appboy client is properly configured.
Requirement Origin Description
Engine SDK Factual Engine SDK In order to successfully integrate Factual’s Engine SDK with Braze, ensure the Engine client has been configured properly and starts successfully. This requires confirming an api key has been acquired and the Engine SDK has been properly imported into the project.
Appboy Client Braze SDK Android Setup Also ensure the Appboy client is properly configured.

Events

The following are custom user events that can be sent to the Braze SDK from Factual’s Engine and are available for both iOS and Android integrations:

User Journey Events

Name: engine_user_journey

Description: User has visited a known Factual location.

Properties:

1
2
3
4
5
6
7
8
9
{
  "name": (string)
  "factual_id": (string)
  "latitude": (double)
  "longitude": (double)
  "user_latitude": (double)
  "user_longitude": (double)
  "place_categories": (string) (place_categories is a comma-separated list of factual category IDs)
}

Circumstance Met Events

Name: engine_circumstance_[CIRCUMSTANCE_NAME]

Description: A circumstance with actionId push-to-braze has been met.

Properties:

1
2
3
4
5
{
  "incidence_id": (string)
  "user_latitude": (double)
  "user_longitude": (double)
}

Circumstance Met At Place

Name: engine_circumstance_place_at_[CIRCUMSTANCE_NAME]

Properties:

1
2
3
4
5
6
7
8
9
10
{
  "incidence_id": (string)
  "name": (string)
  "factual_id": (string)
  "latitude": (double)
  "longitude": (double)
  "user_latitude": (double)
  "user_longitude": (double)
  "place_categories": (string) place_categories is a comma-separated list of factual category IDs
}

Using This Integration

Using a Circumstance in the Braze Dashboard

Step 1: Create a Circumstance in the Garage Web UI

In order to use this integration we first have to set up the circumstance for Engine to trigger our action. This can be done through Engine’s Garage Web UI and Factual’s developer documentation is highly detailed in regards to a circumstance’s usage and creation.

The important step to remember in creating a new circumstance is setting our action to custom by selecting the Add custom action button in the Select an action drop down.

Add Action to Circumstances in Engine

From there, we will need to specify an ID name for our action as shown below. Circumstance Custom Action ID Name

Once it is completed, our updates will happen over the air to any Engine live instance matching your ENGINE/GARAGE API key. Copy your ENGINE/GARAGE API as a reference then click on the Next button and lastly the Push Changes button found on the next screen. Our updates will occur typically in 30 minutes, but this time can also be set programmatically to whatever is needed by your teams.

Step 2: Compose Your Message in Braze

After logging into your Braze dashboard and going to Campaigns, then Create Campaign, you can follow the standard Braze flow to create a new message. To add location names dynamically use the following snippet in either the title or body of your message: {{event_properties.${name}}}. Depending on your use case, it’s recommended to use this snippet in the body of your message as some location have long names and would be truncated in a message title.

Braze Compose New Message

Step 3: Delivery

From within the Delivery tab, select Action-Based Delivery, then in the Perform Custom Event drop down menu, select the custom event you created in the first step.

Every time a user or device meets the criteria of the custom event, like being NEAR (200m) a designated location, Braze will trigger the appropriate action, which in this example is sending a push notification. Braze Select Circumstance

Step 4: Testing Your Implementation

To test in-app and push notifications via command-line, you can send a single notification through the terminal via CURL and the Messaging API. You will need to replace the following fields with the correct values for your test case:

Field Description
YOUR_API_KEY Available on the Developer Console page.
YOUR_EXTERNAL_USER_ID Available on the User Profile Search Page. See documentation on assigning user IDs.
YOUR_KEY1 Optional.
YOUR_VALUE1 Optional.

Curl Command:

1
curl -X POST -H "Content-Type: application/json" -d "{\"api_key\":\"YOUR_API_KEY\",\"external_user_ids\":[\"YOUR_EXTERNAL_USER_ID\"],\"messages\":{\"apple_push\":{\"alert\":\"Test push\",\"extra\":{\"YOUR_KEY1\":\"YOUR_VALUE1\"}}}}" https://rest.iad-01.braze.com/messages/send

Message Output Example

When a user/device meets the engine_circumstance_braze_near (or other specified circumstance) they will receive the below push notification.

Braze Factual Engine Example

Installation

iOS Installation

Installation via Cocoapods

1
2
3
4
5
6
7
8
source 'https://github.com/Factual/cocoapods.git'
source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '10.3'

target 'YourApp' do
  pod 'BrazeEngine'
end

Manual Installation

Download the library from Bintray and add it to your Xcode project.

You must have the Engine SDK already added to your Xcode project in order to use the library properly.

Android Installation

Project Artifacts

For Android, project artifacts are available within Factual’s Bintray Maven repository and can be implemented as shown below.

1
2
3
4
5
6
// repository for the Factual artifacts
repositories {
  maven {
    url "https://factual.bintray.com/maven"
  }
}
1
2
3
dependencies {
  compile 'com.factual.engine:braze-engine:1.1.0'
}

Usage

On iOS, developers can start tracking Factual’s Engine UserJourney and Circumstance events after receiving the engine started callback within FactualEngineDelegate.

1
2
3
4
-(void)engineDidStartWithInstance:(FactualEngine *)engine {
  //Track both user journey and circumstance events
  [BrazeEngine trackUserJourneyAndCircumstancesWithEngine:engine]
}
1
2
3
4
-(void)engineDidStartWithInstance:(FactualEngine *)engine {
  //track only circumstance events
  [BrazeEngine trackCircumstancesWithEngine:engine withUserJourneyEnabled:false]
}
1
2
3
4
5
6
7
8
9
10
11
//Whether user journey events should be sent to Braze
boolean enableUserJourney = true;

/*
Max number of "circumstance_met_at_place" that should be sent to user in case
where multiple places simultaneously trigger the same circumstance. Default is
set to 10.
*/
numMaxEventsPerCircumstance = 3;

BrazeEngineIntegration.initializeBrazeEngineIntegration(androidApplicationContext, enableUserJourney, numMaxEventsPerCircumstance);

Demo App

A demo app implementing the iOS integration can be found within Factual’s Engine Demo repository here, while a demo app implementing the Android integration can be found within Factual’s Demo repository located here.

WAS THIS PAGE HELPFUL?
New Stuff!