factual

Factual Developer Documenation

Welcome to the factual-devdocs developer hub. You'll find comprehensive guides and documentation to help you start working with factual-devdocs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Iterable

Using Factual Location Engine with Iterable

Factual provides an integration between the Factual Location Engine SDK and Iterable'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 Iterable.
1.1.0 Now able to send User Journey Span data from Factual Engine to Iterable.
2.0.0 Compatible with FactualEngineSDK 10 and updated event names.
2.1.0 Sends tags to Iterable. Compatible with FactualEngineSDK 11+.

Custom Events

Iterable Engine sends Factual Engine SDK's events to Iterable 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 Array The 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
name String Name of the place
factual_id String Factual's unique identifier for this place
chain_name String Business chain of this place
tags String Array The tags associated with the circumstance
category_labels String Array 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 Array Localities where the span occurred
region String Array 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 Array 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-iterable

Setup Circumstance

Setup Circumstance

Click Next to Configure your circumstance.

Select Near and select Categories on the SELECT drop-down. On the ANY OF drop-down search for "Coffee" and select Cafe, Coffee and Tea Houses.

Configure Circumstance

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.

Review Circumstance

Review Circumstance

Now your circumstance will be triggered anytime the user is near a coffee shop.

(2) Setup a push notification in the Iterable Dashboard

Create a new app in the Iterable Dashboard by selecting the gear icon, then selection Mobile apps.

Select ADD A NEW MOBILE APP and fill in the relevant information then select CREATE APP and this will take you to the Integrations screen for this app.

Select CONFIGURE on the platform you would like to configure your push notifications for and enter the necessary information for push notifications on either iOS or Android. For more information on setting up push notifications through Iterable, follow their guides here.

Go to the Manage Templates page by clicking the Content tab and selecting Templates.

On this screen select CREATE NEW TEMPLATE, then select PUSH.

Configure your push notification however you like.

Setup Template

Setup Template

When you're done select SAVE TEMPLATE on the bottom left.

(3) Setup workflow in the Iterable Dashboard

Go to the Workflows page by clicking the Messaging tab and selecting Workflows.

On this screen select CREATE NEW WORKFLOW.

Double click the Start when node and for the trigger select Triggered Custom Event and in Event Name enter engine_near_coffee-shop to track whenever a circumstance is met.

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

Drag a SEND PUSH node from the SEND ACTIONS tab onto the workflow and connect the Start when node to it.

Double click the SEND PUSH node and under Campaign Name give this campaign a name. Then, under Pick a template: select the template we created earlier and click UPDATE NODE.

Setup Start Node

Setup Start Node

Connect your Push node to the template we created earlier by double-clicking the Perform Action node, select the template we created by clicking it once, then update node.

Once you are finished you can save the workflow by pressing SAVE on the top left.

Once saved, you can switch the workflow from Disabled to Enabled and users will start to receive notifications whenever they are near a coffee shop.

Completed Workflow

Completed Workflow

(4) Deploy

Once you have enabled the workflow, Engine will send a custom event, in real-time, when a device triggers the coffee-shop circumstance. From there, Iterable takes over and delivers the push notification.

Iterable


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.