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.

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

Note: for the example application to work you must set the action in the DO section below to push-to-iterable. This is the action id and circumstances with this action can be filtered from any other circumstances to be sent to Iterable.

Setup Circumstance

Setup Circumstance

(2) Setup a push notification in the Iterable Dashboard

Create a Mobile Push Integration on the Iterable Dashboard, using APNS or APNS_SANDBOX for iOS or GCM for Android, entering in the proper credentials for each. The Application Name is what you will use in code when settings Iterable's pushIntegrationName, this is required to receive any push notifications.

  • Note you must make a separate Push Integration for both Android and iOS.
Setup Push Integration

Setup Push Integration

Create a Push template on Iterable's Dashboard to include whatever message you would like. Be sure to save!

Setup Template

Setup Template

Create a new workflow on Iterable's Dashboard and have the Start When node point to a Send Push node. Double click the Start When node and have it set on 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.

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. When it's saved you can enable the workflow.

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.