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

VersionChanges
1.0.0Initial release. Tracks circumstances from Factual Engine and sends the relevant data to Iterable.
1.1.0Now able to send User Journey Span data from Factual Engine to Iterable.
2.0.0Compatible with FactualEngineSDK 10 and updated event names.
2.1.0Sends 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

propertytypedescription
incidence_idStringUnique identifier for this circumstance
event_sourceStringAlways factual
tagsString ArrayThe tags 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
nameStringName of the place
factual_idStringFactual's unique identifier for this place
chain_nameStringBusiness chain of this place
tagsString ArrayThe tags associated with the circumstance
category_labelsString ArrayCategories 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
localitiesString ArrayLocalities where the span occurred
regionString ArrayRegions 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_labelsString ArrayCategories 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-iterable

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

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

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

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

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

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

Updated about a year ago

Iterable


Suggested Edits are limited on API Reference Pages

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