API
On your pages
One script, and a slot where each placement goes. It understands DY.API, DY.recommendationContext, exponea.track and br_data, so a shop using those needs nothing else. It honours Global Privacy Control.
<script src="https://harrowsoft.com/bloomfield/s/SITE_KEY.js" async></script>
<div data-bloomfield="product"></div>
<body data-bf-type="product" data-bf-sku="SKU">
Bloomfield.page({type: "cart", cart: ["SKU"], cart_value: 36});
Bloomfield.track("add", {sku: "SKU", qty: 1, price: 18});
Bloomfield.purchase({order: "1001", total: 36, lines: [{sku: "SKU", qty: 2, price: 18}]});
Bloomfield.set({tier: "vip"});
From a server
The same as Dynamic Yield's Experience API, so moving is a change of address. Send your site key as DY-API-Key. A choose names placements by their name or key.
| POST /bloomfield/v2/serve/user/choose | user, selector.names, context.page, options. |
| POST /bloomfield/v2/collect/user/event | user, events. purchase-v1 and add-to-cart-v1 are understood. |
| POST /bloomfield/v2/collect/user/engagement | user, engagements. SLOT_CLICK is understood. |
| POST /bloomfield/v2/collect/user/pageview | user, context.page. |
| GET /bloomfield/recs/{site_key} | JSON for an email or anywhere else: user, sku, strategy, count. |
Managing it from a script
Make a token on your tokens page, and send it as Authorization: Bearer hs_.... It can do what you can, no more.
| GET /overview | What it's worth, and each placement's result. |
| GET /placements | Your placements. |
| POST /placements | name, title, count, steps, holdout, versus. |
| GET /placement/{id} | One, with its proof. |
| PUT /placement/{id} | The same as making one. |
| POST /placement/{id}/status | status: live, paused or draft. |
| POST /preview | placement, sku, cart, returning, likes. What would show, and why. |
| GET /products | q finds one, problem is no_image, no_price, no_category or out_of_stock. |
| PUT /products | products: up to 5,000 changes, without waiting for the feed. |
| GET /product | sku. One, with what's shown next to it. |
| GET /feed | Its address, and what's wrong with it. |
| PUT /feed | url, every (minutes). Admins only. |
| POST /feed/sync | Reads it now. |
| POST /feed/upload | A CSV, JSON or XML file as the body. |
| GET /rules | Your merchandising rules. |
| POST /rules | kind (hide, boost, pin), field, op, value, factor, position. |
| POST /import/orders | A CSV of past orders as the body. |
| POST /import/bloomreach | project, catalog, key_id, secret. Admins only. |
What a placement's steps look like
[
{"when": {"kind": "returning"}, "show": {"kind": "recs", "strategy": "for_you", "title": "Picked for you"}},
{"when": {"kind": "cart_over", "value": 60}, "show": {"kind": "banner", "headline": "Free shipping", "link": "https://..."}},
{"when": {"kind": "always"}, "show": {"kind": "recs", "strategy": "bought_together"}}
]
A strategy is bought_together, viewed_together, similar, same_category, popular, trending, new, for_you, recently_viewed or manual (with skus). A condition's kind is always, returning, new, bought, never_bought, likes, cart_over, device, utm or attr.