Learn how to integrate with Froomle

To be able to give you qualitative recommendations in real-time, we need your online/offline events and as much of your item catalog metadata as you can share.

Integration Overview

We have a number of integration options for each of these, which are described in this section. Discuss and validate the integration options with your Solution Architect at the kick-off meeting.

Item catalog

Froomle needs the items (products / articles / blogposts / …​) you want us to recommend, including any (meta)data we need to take into account in our recommendations. This can be category, brand, price, discount, stock, publication date, …​ .

Different modules require different metadata to function. For details, see the Managing item metadata page and our Examples per industry.

Our preferred item catalog structure is described on the Item Concepts page, however we are flexible to translate the structure as long as individual items each have a unique identifier in your catalog and you provide us with clear mapping logic.

Integration options

This chapter describes the integration options for your item catalog.

Method Steps

Froomle Items API

Customer pushes all updates to the catalog via Froomle’s Items API

- PUT for new items & updates with all metadata in json fields

- DELETE to remove an item

File uploaded on regular basis to Froomle sFTP

File format can be json, csv or xml

Multiple files/sources possible but not preferred

Customer provides file structure & mapping to Froomle standard fields at project documentation milestone

Froomle provides URL, folder & access (whitelisting your IP) and processes the file(s) as soon as they are uploaded

Feed read by Froomle

File format can be json, csv or xml

Customer provides feed information, structure & mapping to Froomle standard fields at project documentation milestone

Customer provides URL & access to Froomle

Froomle sets up process to fetch & ingest the data

Enriched web events

(not recommended)

We can set up a way to construct your product catalog based on the events that you send us, provided that you send the required metadata along in the events.

This is NOT a preferred scenario as it is prone to inconsistencies & less secure.

Events

Knowing what your users are doing on your channels is the basic ingredient for our magic to work. We like to know for each user (anonymized, of course) what pages they visit, what recommendations they see & click, and (if you are selling products) what they buy. For the full list of events please refer to Events Concepts. To determine which events to set up and which not, check out our Examples per industry. If you can provide offline purchase data we can also use that.

For events within Apps, we suggest consolidating all front-end events in a dedicated back-end before transferring them to Froomle to ease any future changes.

Integration options

Method Steps

Events API integration by customer

Froomle & customer agree on the events that will be shared

Froomle provides API specs & access

Customer implements the agreed events on their channels

Froomle can provide JavaScript (GTM / Adobe) template upon request and specification of the library needed (JS framework, front/back-end integration)

Froomle confirms correct event implementation

Published to Froomle PubSub stream

Froomle & customer agree on the events that will be shared

Froomle provides PubSub specs & access

Customer maps events to the Froomle standard structure

Customer links their event stream to Froomle’s stream (file format is flexible tsv, csv or json)

Froomle confirms correct implementation

Batch upload to Froomle sFTP

Applicable only for non-time sensitive data (e.g. offline purchases, historic events)

Froomle & customer agree on the events that will be shared

File format can be json, csv or xml

Multiple files/sources possible but not preferred

Customer provides file structure at project documentation milestone

Froomle provides URL, folder & access (whitelisting your IP) and processes the file(s) as soon as they are uploaded

Historic event data

To avoid a 'cold start' when you get started with Froomle recommendations, there are two main solutions:

  • Preferably you enable the live events integration a few days before going live with recommendations. This way our models can warm-up. As soon as we got a few thousand of events, you can count on qualitative recommendations.

  • As an alternative you can share user events from the period before the go-live of the events integration through batch upload.

Recommendations

Integrating recommendations is the reason why we do all the work! You want to show personalized recommendations to a user. You pass us the user identifier & the module (list_name) you want to fill. We respond instantly with a ordered list of items to show to the user specific to this module.

For some modules the information passed is different but the principle remains the same (e.g. for audience targeting you pass us items and we respond with the users to target with this campaign).

Integration options

Method Steps

Customer connects to Froomle recommendations API

Customer & Froomle describe the modules in scope and any metadata needed in the response.

Froomle enables API access

Customer implements API call & response processing

Customer implements the layout of their module

Froomle confirms correct implementation of the recommendations

Javascript template provided by Froomle

Customer & Froomle describe the modules in scope, the context where the library will be integrated and any metadata needed in the response.

Froomle provides JS template to fetch recommendations, and a default html structure.

Customer adapts the layout of their module adapting html & css.

Froomle enables API access

Froomle confirms correct implementation of the recommendations