Rev 1.3 - 04.02.2022 - For import widget V0.8.0
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)
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ür iPhone und Android</a>
</div>
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ür iPhone und Android</a>
</div>
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ür iPhone und Android</a>
</div>
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.
<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>
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"
}
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.
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>
Information about structured data
Structured data testing tool:
https://search.google.com/structured-data/testing-tool/u/2/?hl=de
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}
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"});
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
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.
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.
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.