Froomle Shopify App Handbook

This page provides guidelines for Shopify webshops to install, configure and use the Froomle app.

Froomle App basics

The Froomle app can be downloaded and installed on your webshop using this link: https://apps.shopify.com/froomle . Please share this with your webshop admin/development.

After installing the Froomle app, the Help Center within the app will give you all necessary information to use the app. The blue (?) can be used to reach our support team.

Shopify 1

Preparing for Froomle recommendations

Our team will contact you for a kick-off call to activate & deploy the Froomle modules you want.

As a preparation we need your feedback on a number of questions:

  • Are you using a custom theme?

  • Are you using Shopify 2.0

  • Do you want to use the Froomle standard module layout or customize it?

  • Do you intend to benchmark Froomle? We offer a benchmark against no recommendations or against Shopify default recommendations as part of our standard.

Before the kick-off, we kindly ask you to install the Froomle application.

Froomle will then prepare our environment and any custom plan, so we can go live with recommendations during the kick-off meeting.

Customizing the layout of Froomle module using a standard Shopify theme

Our app provides following features out of the box from the theme editor:

  • Choosing different recommendation modules,

  • Labeling your box,

  • Choosing the number of recommendations header and font size,

  • Configuring the image ratio & cropping.

Shopify 2

If you require further styling you can style your modules using CSS, which requires limited technical expertise. To do this navigate to Edit Code on your webshop Theme page.

Shopify 3

As long as the HTML and class names are untouched, everything should work correctly. When the recommendations load, the loading state in grid items are replaced with a HTML structure like in the JS example below. You can see all of the variable classes here.

<div class="froomle-grid__item">
    <div class="froomle-image-container froomle-image-container--${IMAGE_RATIO}">
        <img alt="${product.title}" class="froomle-image ${IMAGE_RATIO !== " adapt"
            ? 'froomle-image--force-aspect-ratio' : '' } ${CONTAIN_IMAGE===true? 'froomle-image--contain'
            : 'froomle-image--cover' } "
            loading=" lazy" src=${product.featured_image} />
        ${data && data.demoMode ? demoBanner : ""}
    </div>
    <div class="froomle-footer-container">
        <a href="${product.url}" class="froomle-product-title">${product.title}</a>
        <div class="froomle-price-wrapper">
            ${ product.compare_at_price ?
            `
            <span class="froomle-product-price--line-through">${moneyFormatter.format(product.price /
                100)}</span>
            <span class="froomle-product-price">${moneyFormatter.format(product.compare_at_price /
                100)}</span>
            `
            : `<span class="froomle-product-price">${moneyFormatter.format(product.price / 100)}</span>`
            }
        </div>
    </div>
</div>

Using Froomle on Shopify webshops with a vintage or custom theme

If your theme does not fully support Shopify’s visual editor or you need a greater degree of customization then we recommend modifying the theme’s code directly.

We describe the available options on this page:

  1. Deploy modules by adding a placeholder tag

    • The easiest way to add Froomle modules to a vintage theme that does not support the visual editing options introduced with Shopify’s Online Store 2.0. Provides the same level of customization as the app block in the visual editor.

  2. Deploy modules by calling the Froomle APIs directly

    • This option is preferred if you need to make advanced modifications to your Froomle modules. This could be adding/removing information, alternative layouts, multiple images, …​

    • It gives you access to the full flexibility of the Froomle APIs, but requires additional technical skills

Option 1: Deploy modules by adding a placeholder tag

Step 1: Link to Froomle’s Shopify script

Navigate to the code editor for your theme and insert following script in the <head> section of your theme.liquid layout, as illustrated here:

<script src="https://cdn.froomle.com/js/froomle-shopify-1.min.js"
        data-customer-id="{%- if customer -%}{{ customer.id }}{%- endif -%}"
        data-product-id="{%- if product -%}{{ product.id }}{%- endif -%}"
        defer>
</script>

Please note that you still need to have the Froomle app installed and the app embed block enabled.

Step 2: Insert module placeholder tags

The Froomle script replaces all HTML tags on a page that have a data-froomle-recommendations attribute with a Froomle recommendations module. For example, following tag inserted in the product page template would look similar to this:

<div data-froomle-recommendations
     data-header="Trending products"
     data-type="most_popular"
     data-size="3">
</div>

Modules inserted through these placeholders can be customized by adding one or more of the following attributes to the placeholder tag:

  • data-type: Type of recommendations to display. Valid options are listed below. Defaults to "most_popular".

    • "most_popular"

    • "best_sellers"

    • "recommended_for_you"

    • "discover_for_you"

    • "recently_viewed"

    • "recently_purchased"

    • "related_products" (product page only)

    • "complete_your_purchase" (product page only)

    • "you_may_also_like" (cart page only)

  • data-size: Maximum number of recommendations to display. Defaults to "4".

  • data-header: Header to display above products. Defaults to "Recommended products".

  • data-header-size: Size of the header font, in pixels. Defaults to "24".

  • data-font-size: Size of the product title font, in pixels. Defaults to "16".

  • data-image-ratio: Ratio of the product image. Valid options are listed below. Defaults to "landscape".

    • "adapt"

    • "square"

    • "landscape"

    • "portrait"

  • data-contain-image: Display the entire product image without cropping. Defaults to "true".

If the result does not look as expected, try checking your web browser’s console for warnings by pressing F12. Any misconfigurations will be reported here. Also remember to click the "Save" button in the code editor after any changes.

Option 2: Deploy modules by using the Froomle APIs

If you want further customization, you can use the Froomle APIs directly. They basically return you the item identifiers & metadata to show on each position, and you can customize everything else.

Step 1: URL & Authentication

We will host your Froomle instance on a specific URL which will be shared with you before the Go-Live:

<subdomain>.froomle.com

Froomle will provide you with a $CLIENT_ID and $CLIENT_SECRET through the use of this one-time-secret link (note: this link is only valid once!) Afterward, these credentials will need to be used to retrieve a Bearer token. They are valid for a certain period, which Froomle will communicate. These tokens can then be used to retrieve recommendations (recommendations API).

They are not required for the events API.

They can also be used to manage item metadata, but this is handled through Shopify.

The credentials will be communicated at the moment the items API is set up from the Froomle side.

curl --request POST \
  --url "https://{subdomain}.froomle.com/oauth/token" \
  --header "content-type: application/json" \
  --data "{\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\"}"

As soon as the shop has the app downloaded & embed block enabled, the app will set the cookies and send the events correctly you just need to know which cookie to use in your recommendations (see step 2), clicks, impressions (see step 3).

  • item_id = product.id (for pageviews, impressions, clicks)

  • item_id = variant.id (for add to carts and purchases)

  • user_id = customer.id (for logged in users)

  • device_id = localStorage.getItem('froomle-device-id'); (for all users)

  • blacklisted_collections

  • cart_items

Step 2: Fetch recommendations using our Recommendation API

Use our standard integration as described on the Integration Handbook.

You’ll need to fetch recommendations from our Recommendations API. for each module, and can customize the output according to your needs.

💡 Note that some modules require context_item, context_category, or other variables to function correctly. Froomle support can help you detail this out.

{
  "device_id": "the-cookie-id-123",
	"user_id": "the-user-id-123-like-cookie",
	"lists": [{
		"list_name": "discover_for_you", // the label of the box, has to be unique
		"module_id": "discover_for_you", // the module id, has to match our module library
		"list_size": 4, // the number of items you want to request
		"blacklisted_collections": []  // collections we shouldn't recommend
	}],
	"context_item": "10329209998", // the item identifier the user is on currently (if applicable)
	"context_item_type": "product", // the type of item the user is on currently (if applicable)
	"page_type": "item_detail",
	"channel": "mobile-app"
}

By default, Froomle only returns the item_id’s of the recommended articles in the recommendation response. However, we can also communicate any information you share with us, back to you. This could save you some time fetching the information from your own back-end. Just let us know what you’d like to see in your recommendation response.

Standard example:

{
    "device_id": "the-cookie-id-123",
		"user_id": "the-user-id-123-like-cookie",
    "lists": [
        {
            "items": [
                {
                    "item_id": "def-567",
                    "rank": 1 // we can add additional metadata here if needed
                },
                {
                    "item_id": "abc-1234",
                    "rank": 2
                },
                {
                    "item_id": "abc-123",
                    "rank": 3
                }
            ],
            "limit": 3,
            "list_name": "continue_reading",
            "list_size": 3
        }
    ],
    "request_id": "4",
    "user_group": "froomle" // fields Froomle uses for AB testing, you can measure these fields to monitor our performance if you like
}

From this response, you can save request_id, user_group in a variable so you can use it when sending the clicks/impressions events.

Step 3: Trigger integration events to Froomle events API

In order to work optimally and to report on results accurately, Froomle needs you to send analytics events from the activity on your modules, using our Events API.

We need you to send the following events for each of your modules:

Impression:

  • When a user sees a Froomle recommendation.

{
    "events": [
        {
            "event_type": "impression",
            "page_type": "article_detail",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "list_name": "continue_reading",
            "action_item": "test_item_123",
            "action_item_type": "article",
            "request_id": "12345_see_recommendation_response",
            "channel": "www-desktop",
            "user_group": "froomle_x_see_recommendation_response"
        }
    ]
}

  • user_id = customer.id (for logged in users)

  • device_id = localStorage.getItem('froomle-device-id'); (for all users)

  • action_item = product.id

Click on recommendation

  • When a user clicks on a Froomle recommendation (and is directed to the product detail page or has added the product to their cart directly.

{
    "events": [
        {
            "event_type": "click_on_recommendation",
            "page_type": "article_detail",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "list_name": "continue_reading",
            "action_item": "test_item_123",
            "action_item_type": "article",
            "request_id": "12345_see_recommendation_response",
            "channel": "www-desktop",
            "user_group": "froomle_x_see_recommendation_response"
        }
    ]
}

  • user_id = customer.id (for logged in users)

  • device_id = localStorage.getItem('froomle-device-id'); (for all users)

  • action_item = product.id

Other events (pageviews, purchases, add to carts, …​ ) are collected through our app.

Step 4: Deploy & enjoy!

You’re good to go!

Additional Froomle Insights

As part of the app, Froomle offers a standard Shopify Insights dashboard.

Via the Froomle Recommendation Portal you can simulate and review how personalized recommendations will look like, for different personas using your website. The tool also allows to consult Froomle Insights on KPI’s, benchmark results and audience insights.

These are available in all plans during trials, but only in advanced plans after a trial.