Web-to-App Integration

Rev 1.3 - 04.02.2022 - For import widget V0.8.0

Widget integration

The technical integration is very simple. It requires the placement of a script and a small widget on your website (see below). The element to be rendered as widget needs two attributes to be set:

data-bring-import

reqiured

Url to the file or website to be imported. If pointing to a file with the extension .json, the file content gets interpreted and imported. If not, the linked destination gets parsed and imported. If the attribute has no value, the current page where the widget is located gets parsed.

the following features only work when the source gets parsed by Bring!

  • that auto assign of icons for non catalog items

  • calculation of quantity (see below)

data-bring-import-version

not required

The version of the json file defined with data-bring-import. Only necessary if a data-bring-import points to a json file.

data-bring-language

default = de

The language of the text in the button. Supported values:

  • de

  • en

  • fr

  • it

data-bring-theme

default = dark

The style of the theme. Supported values:

  • dark

  • light

  • blackandwhite

data-bring-base-quantity

default = 4

If your recipe site supports adjusting the quantity (e.g. for 6 people), this defines the base quantity the recipe has by default

data-bring-requested-quantity

default = 4

If your recipe site supports adjusting the quantity (e.g. for 6 people), this defines the requested quantity. This value can be set via JavaScript (see below for more information)

data-bring-requires-consent

default = false

If your page requires user consent to actaully track anything to Google Analytics.
If you set this attribute to true, you may inform the widget about the consent given by the user via JavaScript (see below for further information)

Sample integrations

Current location

This is our preferred integration and also the simplest one.

<script async="async" src="//platform.getbring.com/widgets/import.js"></script>

<div data-bring-import style="display:none">

<a href="https://www.getbring.com">Bring! Einkaufsliste App f&uuml;r iPhone und Android</a>

</div>


Linked location

To link an external recipe use the data-bring-import attribute.

<script async="async" src="//platform.getbring.com/widgets/import.js"></script>

<div data-bring-import="http://www.myrecipe.com" style="display:none">

<a href="https://www.getbring.com">Bring! Einkaufsliste App f&uuml;r iPhone und Android</a>

</div>

In French and light theme, with requested quantity calculation

In this case, the requested quantity has to be by your page via JavaScript

<script async="async" src="//platform.getbring.com/widgets/import.js"></script>

<div data-bring-import data-bring-language="fr" data-bring-theme="light" data-bring-base-quantity="2" style="display:none">

<a href="https://www.getbring.com">Bring! Einkaufsliste App f&uuml;r iPhone und Android</a>

</div>

Integration on a button without java script or from an app

As an alternative to the java script widget we also provide the possibility to set the href of an anchor tag linking to a resource on our backend. We will then parse the given URL and perform a HTTP 307 Temporary Redirect with the deeplink to our app in the Location header.

In order to use this integration you need to set the following parameters as query parameters:

url

reqiured

Url to the file or website to be imported. If pointing to a file with the extension .json, the file content gets interpreted and imported. If not, the linked destination gets parsed and imported.

This parameter should be URL encoded!

the following features only work when the source gets parsed by Bring!

  • that auto assign of icons for non catalog items

  • calculation of quantity (see below)

source

reqiured

Needs to be set to web

baseQuantity

default = 4

If your recipe site supports adjusting the quantity (e.g. for 6 people), this defines the base quantity the recipe has by default

requestedQuantity

default = 4

If your recipe site supports adjusting the quantity (e.g. for 6 people), this defines the requested quantity.

Example for a button rendered on a website

<a href="https://api.getbring.com/rest/bringrecipes/deeplink?url={the url of your recipe}&source=web&baseQuantity=4&requestedQuantity=4">

{your rendering of the button comes here}

</a>

Example for an integration inside an app (Android, iOS,..)

In order to implement a recipe import button inside an app (e.g. Android or iOS) you can perform either a GET or a POST call. As a response to the GET call you will receive a HTTP 307 Temporary Redirect with the deeplink to our app in the Location header. For a POST call you deliver all the neccessary information in the request body and will then get the deeplink to our app in the response.

Example GET:

"https://api.getbring.com/rest/bringrecipes/deeplink?url={the url of your recipe}&source=web&baseQuantity=4&requestedQuantity=4">

Example POST:


curl --location --request POST 'https://api.getbring.com/rest/bringrecipes/deeplink' \

--header 'Content-Type: application/json' \

--data-raw '{

"url" :"{the url of your recipe}",

"baseQuantity" : 4,

"requestedQuantity": 4,

"source" : "app"

}'

Request:

{

"url" :"{the url of your recipe}",

"baseQuantity" : 4,

"requestedQuantity": 4,

"source" : "app"

}


Response:

{

"deeplink": "https://go.getbring.com/xzy"

}


Import with parser

The parser implements the recipe specification from schema.org (https://schema.org/Recipe). Information added to your site that follows this schema will also be used by search engines like Google to present your recipe in their search result. Adding this schema information will help us parsing your recipe, but it will also help you to improve the presentation of your recipes. This is also required if your site supports adjusting the import quantity.

Example Schema.org Markup for Bring! Recipe Parser

Bring parses the content of ingredients to figure out itemId and spec. With that information we figure out altIcon and stock.

<div itemtype="http://schema.org/Recipe">


<h1 itemprop="name">[name]</h1>

<div itemprop="tagline">[tagline]</div>

<div><span>By </span><span itemprop="author">[autor]</span></div>


<img src="[imageUrl]" itemprop="image"></img>

<p>

<div>

<span>Category: </span>

<span itemprop="recipeCategory">[category]</span>

</div>

<div>

<span>serves: </span><span itemprop="yield">[yield]</span>

</div>

<div>

<span>Cooking time: </span><span itemprop="prepTime">[time]</span>

</div>

<div itemprop="nutrition" itemtype="https://schema.org/NutritionInformation">

<span>provides: </span>

<span itemprop="calories">[calories]</span>

</div>

</p>

<ul>

<li itemprop="ingredients">[ingredient]</li>

<li itemprop="ingredients">[ingredient]</li>

</ul>

</div>

Interacting with the widgets via JavaScript

Late render

When loading the page the script waits until the DOM is completely ready and then parses the page for elements with the required attributes. If it finds any, it transforms them into import buttons. In some cases, the elements might not yet exist at this stage (e.g. when using dynamic frameworks like Angular or React). In this case it's possible to request the creation of import buttons via JavaScript.

window.bringwidgets.import.render([HTMLElement], config);


The config is a JavaScript object of this form where at least the url has to be set:

{url: string, version: string, language: string, theme:string, baseQuantity: string, requestedQuantity: string}

Example Integration

HTML

<span>This is a sample recipe</span>

<div id="importButton">here we place the Bring! import Button</div>

<span>And here are the ingredients</span>

....

Javascript

var element = document.getElementById("importButton");

window.bringwidgets.import.render(element, {url: window.location.href , theme: "swissmilk", language: "de"});


Set requested quantity

Many pages let the user choose how many people he needs the ingredients for. So after the page changes its content, it has to notify the widget about the change.

window.bringwidgets.import.setRequestedQuantity(quantity: number);

This sets the requested quantity for all the widgets on the screen. Be aware that the parser calculates the values based on the value set via data-bring-base-quantity which by default is set to 4.

Here two examples:

  • Default is not set (and therefore is 4) and setRequestedQuantity is set to 6 -> the server will multiply all values by 1.5.

  • If your recipe is for 2 people and you therefore have set data-bring-base-quantity="2" and then import for 6 people -> the factor used by the server is 3.0

Set base quantity

Similar to setRequestedQuantity, setBaseQuantity allows to set the base quantity of the recipe. This is necessary if our parser cannot get the base quantity from the site's HTML source.

window.bringwidgets.import.setBaseQuantity(quantity: number);

This sets the base quantity for all the widgets on the screen.

Set url

This function allows setting the url on demand. The url will also be used when the user navigates from Bring! back to your recipe.

window.bringwidgets.import.setUrl(url: string);

If your recipe site supports setting the quantities via url, it might be best if you set the url via setUrl. If the user imports a recipe for e.g. 6 Persons and later uses Bring! to go back to your recipe, the recipe will be shown with the right quantities. NOTE: In that case, there is no need to set the base quantity or requested quantity.

Set consent given all

This function allows informing the widget about the consent given when consent is needed. (See attributes section)

window.bringwidgets.import.consentGivenAll();

It is only after this function is called that the widget tracks information to Google Analytics.