Discovery glossary

Account

Within the Bloomreach resource hierarchy, an Account is the base-level organizing entity. Each Account is an independent instance of the Bloomreach application, configured to its requirements.

An Account completely isolates all Bloomreach resources from other parts of an Organization. If you want a completely isolated setup for a part of your business, Accounts are the ideal boundary to work with. For example, if you have multiple brands, each brand would likely be associated with its Account.

Analytics

Bloomreach Analytics tracks performance metrics and results of interactions between your site(s) and visitors. The interactions we track include Visits, Sessions, Revenue, Conversions, and Bounces. Read the documentation for more details on how each of these is calculated.

All Analytics data is derived from the Bloomreach Pixel. Bloomreach collects Analytics interactions at the Site level but can aggregate the information up to an Account level.

API Call

This refers to an HTTP (GET/PUT/PATCH/POST) request made to Bloomreach Discovery module endpoints - Search, Category, Suggest, Recommendations, Thematic, and Catalog Management. Except for the Catalog Management API, all other APIs only support GET methods.

Read the documentation to learn more.

Attributes

Attributes are elements within a product feed that define a product or variant. Attributes refer to a type of data that is found across a catalog but may vary for each item. The attributes that you send us in your feed are stored as fields in the index.

Attribute types

For product catalogs, Bloomreach has mandatory reserved attributes, conditionally reserved attributes, and custom attributes.

1. Mandatory reserved attributes are the minimum attributes that must be sent to Bloomreach for the search to function optimally. These include:

• title
• category_paths
• price
• description
• url
• availability
• brand
• thumb_image

2. Conditionally reserved attributes are an additional set of attributes that are not required to be sent, yet require specific naming conventions and formatting. The full list of these attributes can be found here.
3. Beyond these, you can send any Custom attributes in your feed, and Bloomreach will process and index them accordingly.

Other details

• Attributes exist at either the product level or the variant level. For example, ‘title’ is an attribute that determines the overall title for the product, but ‘price’ may differ per variant.
• Category paths define the category tree information and determine how products relate to categories on your site.

Catalog

A Catalog is a collection of product or content data specific to a single language. For a language-specific search experience, each language requires its own Catalog.

Examples of types of data prevalent in e-commerce Catalogs include products, variants, price lists, content, etc. For Bloomreach, Catalogs will generally contain up to 3 types of information:

• Product OR Content data

• Categories data

• Views (optional)

  

📘

Domain and domain_key

Domain refers to a product catalog.

domain_key is the identifier of the specific product catalog in your account you want to make a search request against. This is also the same as the product catalog's name. If you are making a Content Search request, you do not supply this value. Instead, you would use the "catalog_name" parameter to specify the content catalog to make a request against.

Catalog Type

At Bloomreach, there are two types of catalogs - Product and Content.

• Product Catalogs: These contain information about the products you want to make searchable (and ultimately sellable) on your digital domains. The information about these products is required for Bloomreach’s Search, Suggest, Recommendations, and Category APIs.
• Content Catalogs: These contain the content and other information (e.g., recipes) you want to make available on your site. This is required if you're using the Bloomreach Content Search feature.

Though they house different types of data, Product and Content catalogs are ultimately processed similarly.

Category API

The part of the Search API for retrieving product results from within your specified categories. A valid category-id is sent in the query (q) parameter of the request, and the corresponding product results are received as a response.

Request identifier: “category”

Read the documentation to learn more.

Currency

Each Account is designated a default Currency, in which all the Analytics data related to revenue is processed and displayed in the Bloomreach dashboard.

If you're selling in multiple currencies, you must configure the br_data.currency parameter in the conversion pixel to report the currency of each sale. Bloomreach then normalizes the data into the default Account currency for display in the Bloomreach dashboard. The normalized data is also used as signals to inform underlying Bloomreach algorithms.

This Currency designation is shared across the Environments within an Account. Read the documentation to learn more.

Document

A Document is a data record that represents either a searchable product, variant, or content item along with all its attributes. Documents comprise product records that have been transformed according to catalog configurations and stored in Bloomreach.

What's included in Document count?

• The total number of Documents reflects the total number of products and variants within each Bloomreach Catalog. Suppose your catalog contains a white shirt. This appears as a single Document. If the shirt has variants in red, blue, and yellow, each variant also appears as a separate Document. This results in a total of 4 Documents for the product.
  
• We only count documents in Production for licensing. Note that in the Staging environment, the documents cannot exceed 1.5 times the licensed amount used in Production.
• The total count of Documents also includes the additional Documents needed to display distinct products and product variants for multi-view use cases (e.g. BOPIS, fitment, B2B part numbers, custom catalogs, custom price lists, multiple currencies).
  
  Let’s say the white shirt in your catalog from above sells for $15 in the US, but you charge €20 in France. Then the white shirt must have both a US version and a French version in your Index, corresponding to separate Documents, to represent the adjusted pricing. This results in 2 Documents for the white shirt. Given that this white shirt also has red, blue, and yellow variants, each with a French version in the Index, the total number of Documents for this product is now 8.

Email Recommendations APIs

API requests that dynamically retrieve personalized product recommendations when your customer opens your promotional email. The Email Recommendations are delivered as Image and link pairs (which are generated by the API calls). Email recommendations are not measured by the Usage app.

Read the documentation to learn more.

Environment

Each Bloomreach Account always comes with a Staging Environment provisioned by default, each with its own Catalog, API endpoints, Rules, and Synonyms. The provision of a Production Environment is optional. Environments can be used to support your deployment requirements for QA, testing changes, and more. Different environments can have different catalogs.

Read the documentation to learn more about environments.

Experience

Experience refers to what the end-user sees or interacts with, such as websites, mobile apps, or connected smart devices.

In the context of Discovery, it refers to the unique shopping experience that you can create using a combination of different resources (say, Sites and Site Groups). This experience can be observed with Analytics and optimized with merchandising rules.

Facets

Facets on a search page reflect the product attributes belonging to that set of products. The system returns the best facets based on how relevant they are to the query. Facets are ordered based on facet engagement metrics for that particular query or category. For example, if customers search for "paper" and engage with the "paper brightness" facet over the "brand" facet, then "paper brightness" will be ranked higher.

You can create Facet rules at the Account level to tweak facet order or facet names. Read the documentation to learn more.

📘

Facets should not be confused with Filters. Filters enable you to narrow the search results based on the Facet(s).

Feed

The contents of your business’s Product Catalog are sent to Bloomreach via a product feed. The product feed provides all the critical information from a catalog Bloomreach Discovery needs to provide a search result.

Index

After importing records from the feed, Bloomreach executes an Index command that compiles and structures underlying data records into an index. By constructing an index, Bloomreach is able to achieve fast search responses. An index is contained within a Catalog.

Language

A Catalog represents your data in a single language. For Bloomreach, Catalogs must be restricted to a single language to support semantic understanding and searchability of the data involved.

Organization

At Bloomreach, an Organization represents a Bloomreach customer and is the root of the entire customer resource hierarchy. This hierarchy allows you to

• Map your company structure into the Bloomreach Organization.
• Provide resources at different levels of the hierarchy for access management (IAM) policies.
• Logically connect many Bloomreach rules that influence search & merchandising behavior on your digital domain(s).

As the root, the Organization is the container for your account(s) and users. An Organization may contain multiple Accounts; this is useful when there are significant management differences across parts of your organization.

Organization administrators have central control over all resources in the hierarchy. Roles can be granted at the Organization level, and inherited by all resources below it.

Page Views / Events

Page Views and Events are types of Pixels.

Page View pixels are tracked when the page is loaded. For example, when the Product detail page loads, we track the “Product Page View” pixel.

Event pixels are tracked when an end-user activity is triggered. For example, the “Add to cart” Event pixel is fired when the end-user adds a product to a shopping basket.

The most common and important pixel types are

• Product page view
• Category listing page view
• Search results page view
• Conversion page view
• Add to cart event
• Search and suggest events
• Widget interaction events

Permission

Permissions are the rights associated with any given Role. This can be either to access different dashboard apps or various resources in your resource hierarchy. Read the documentation to learn more.

Pixel Tracking

Pixel is a code snippet you must add to your site’s pages to track and send necessary data to Bloomreach. The captured pixel data is stored on the Account level.

What activities do pixels track?

Pixel counts an individual hit, an instance when tracking was executed, either by page load or user activity. Pixels track your customers' activities on your site, such as clicks on products, searches, add-to-cart, etc. This tracking adds behavioral learning data to Bloomreach's algorithm. Over a period of time, data captured by the pixel amounts to a powerful, intuitive search solution that powers all Bloomreach solutions.

How are pixels tracked?

Pixel tracking is usually done through a JavaScript code snippet that you must add to your site’s pages to capture and send necessary data to Bloomreach. Alternatively to Javascript code, there are SDKs for tracking from iOS and Android applications.

Read the documentation to learn more.

👍

It’s essential that you keep the pixel tracking in high quality - correct and complete. Degradation of pixel data quality causes degradation of performance of Discovery features, especially Search quality, Insights, and other dependant Loomi-powered features.

Recommendations and Pathways API

A request for retrieving products in different Recommendations and Pathways widgets like Frequently Bought Together, New Arrivals, etc. Product recommendations create more opportunities for upsells and cross-sells.

Read the documentation to learn more.

Record

A Record is a piece of unmodified information that you send Bloomreach in a product or content feed. This raw information can include details like the product ID, attributes, variants, and views.

When you configure attributes, we take these records and index them within our Search platform, at which point they become Documents. In multi-view use cases, a single record can turn into multiple documents.

Region

An Account’s Region specifies the area where a copy of your data is stored. The region’s data privacy laws apply to this data. Once a region is set for the account, it cannot be changed. The available region options are

• us (United States)
• eu (Europe)

Role

A Role defines a set of Permissions that grant read and/or write access to different apps within the Bloomreach dashboard. Roles can be granted to the Organization, Account, or Site resources in the resource hierarchy. If a Role is given to a resource at a higher level, it is inherited by all levels below it.

The Organization's IAM Admin Role is responsible for assigning Roles to other Users in the Organization. Administrators are given the ability to create or delete Users and to assign or revoke Permissions to Users.

See the documentation for more information on which Roles exist.

Rules

Rules are the merchandising configurations/changes that enable you to manually curate the shopper’s search experience. Rules can be used to hand-pick your product assortments and strategically adjust the search results shown by the algorithm. These can include

• ranking rules (product boost, bury, slot, sequential lock)
• recall rules (product blocklist, add to recall)
• attribute-based rules
• synonym rules
• redirect rules
• autosuggest rules
• group rules
• facet rules

Read the documentation to learn more about the process of creating rules using the merchandising dashboard.

Search API

A request for retrieving results about products and other content on your site.

Request identifier: “keyword”. See Catalog type dimension to separate product and content search request.

Read the documentation to learn more.

Site

A Site contains a unique combination of catalog and view (optional). Thus, while a Site must have a catalog, it may or may not have view(s). Different combinations of catalog and view can result in different site implementations, such as

• Single site no view: This implementation has a single catalog. Suppose this is an English catalog.
• Single site single view: This implementation has a single catalog with a single view. Suppose there is one English catalog that has a separate view just for Australia.
• Single site multi-view: This implementation has a single catalog with multiple views. Suppose there is one English catalog with separate views for Australia and Ireland.
• Multi-site no view: This implementation has multiple catalogs with no views. Let's say you have 2 catalogs, one in English and one in French.
• Multi-site single view: This implementation has multiple catalogs and a single view. Let's say there are separate English and French catalogs. The French catalog has a separate view for Canada.
• Multi-site multi-view: This implementation has multiple catalogs and multiple views. Say there are English and French catalogs. The English catalog has separate views for the USA and Canada. The French catalog has different views for France and Canada.

Sites are tracked and reported in Analytics using the domain_key and view_id properties of events.

Site Group

A Site Group defines a group of sites under a global Account.

Suggest API

A request for retrieving autocomplete suggestions in a dropdown list as the visitor types in the search box.

Request identifier: “suggest”

Read the documentation to learn more.

Synonyms

A synonym is a term that means the same or about the same as another term. Synonyms enhance the entered search queries to give back the best possible result set.

Synonyms that inform search come from three major buckets:

1. Global Synonym Library: Synonyms common to all merchants. These are periodically generated from multiple sources - product feed, web crawling, and user engagement data on e-commerce sites.
2. Bloomreach Generated Synonyms: Based on shoppers’ search histories and patterns on your site, our system is able to intelligently and accurately generate new synonym pairs. Suppose a shopper searches for “kicks” but does not engage with the results, and then searches for “sneakers” and makes a purchase. If a similar pattern is observed frequently, and the relationship is validated by observing web-wide language, Bloomreach Site Search will link the two terms as a synonym pair.
3. User-Created Synonyms: Synonyms that you or the Bloomreach team enter manually through the Bloomreach Dashboard.

Read the documentation to learn how to manage Synonyms on the Dashboard.

Thematic API

A request for retrieving thematic page results focused on long-tail themes. Requests for SEO widget serving are not measured by the Usage app. Request identifier: “thematic”.

Read the documentation to learn more.

User

User refers to any individual in your Organization who will be using the Bloomreach platform. Users are managed at the Organization level by Identity and Access Management (IAM) Admins. Typically user management is handled by either a business user or an IT admin in the Organization.

Organization's IAM Admin grants Roles to users and allows them to access select resources in the Organization's resource hierarchy. Organizations can thus ensure that their teams are working only on Bloomreach functionality relevant to them.

📘

User does not refer to your site’s visitors, but to you as a Bloomreach product user.

Variant

Products can have Variants, such as different options for colors and sizes. Variants can have a distinct set of attributes that differ from the base product attributes. For instance, you may send ‘title’ as a common attribute for the overall product but send different ‘price’ values per variant.

Every variant has a unique SKU, distinct from the base product's SKU. SKUs are unique identifiers assigned to items, including product variants and standalone products. While all Variants have SKUs, not all SKUs necessarily represent Variants of a Product.

Views

Views allow you to display products with some different data variations across your customer base depending on who’s viewing the products or content. They are virtual snapshots of a catalog with distinct representations of a product or variant.

For example, you may want to account for variations across different countries (such as currencies), enable B2B account pricing, or simply partition parts of your main catalog for different customer groups (e.g., platinum tier, gold tier, silver tier, etc.)

A multi-view implementation is where you send view information in the feed. This data is used in the experience layer to determine the types of products or content made available to shoppers depending on their respective View.

The effective impact on your index is that the number of documents per record in a feed will likely increase. If a single record has three separate views, Bloomreach needs to index each of these views as separate documents.

Read the documentation to learn more about Multi-view catalogs. To interact with View data, follow this guide.

View Membership

When a parent product is listed under a View but without variations to the product data, this is called View Membership. View membership indicates that the parent product can exist within that specific view.

Suppose p123 is the parent product. For the UK View, this product appears as uk123. If uk123 (UK version) contains the same product data as p123 (parent product), Bloomreach will recognize that p123 should remain as is in the UK view.

Please note that View Membership has no impact on the document count.

View Overrides

Product-level views, often called View Overrides, include all the variations to product information in the catalog for any specific view of the catalog. These variations override the parent product data when the shopper sees the product in a specific View.

Impact of View-Overrides on Index

View overrides create multiple documents for a single item.

Suppose p123 is the parent product. For the UK View, uk123 is the View override for p123. This means that uk123 may have some similar attribute values as p123, but will also have different variants and attribute information (say price).

When Bloomreach receives uk123 in the feed, we override the original price of p123 and show the price of uk123 in the UK View. This requires creating a separate document for uk123 in the UK View.