Product Presence
Overview
Product Presence is a feature that allows you to track whether expected products are present on shelves at specific retail locations. The system compares products detected through Image Recognition (IR) against a configured list of expected products, calculating a presence rate for each location and mission response.
Creating a Product Presence Configuration
Creating a Product Presence Configuration
Navigate to Configuration: Go to the Reporting tab and select Insights. If no configuration exists, you will see a "No configuration found" message.
Create New Configuration: Click "Create New Configuration" to begin.
Configuration Name: Enter a descriptive name. These names will be visible to mobile users.
Configuration Type: Product Presence is auto-selected as it is currently the only type available.
Select Place Groups: Choose the place groups that should be included in this configuration.
Select Photo Types: Choose one or more photo types (e.g., "Photo Grid Shelf Multi-Category US Shelf"). Multiple selections are allowed.
Set Start Date: Select when the configuration should begin tracking. Setting a future date will put the configuration in "Scheduled" status.
Set End Date: Maximum duration is 6 months from the start date.
-
Upload Product List: Choose whether to upload products individually or in bulk.
- Individual upload: Upload a CSV containing the Brand Bank GUID, External ID, or UPC for each product you want to track.
- Bulk upload: Create multiple configurations at once from a single CSV. See Bulk Configuration via CSV below.
Create: Click the Create button to finalize the configuration.
NOTE: If a product matches more than one identifier type, it's matched in this priority order: BB GUID, then External ID, then UPC. You can also include a product name in your upload. The name is only saved for unmatched products. Matched products use the name on file in BrandBank.
Bulk Configuration via CSV
Bulk upload lets you create many configurations in a single file instead of building each one individually in the UI. This is intended for admins managing large product catalogs across many locations.
To create configurations in bulk:
- From the upload screen, select Bulk Upload.
- Review the on-screen instructions and download the example file if you need a template.
- Upload your completed CSV.
- You'll see a confirmation toast, then be redirected to the upload results page.
- From the results page, you can download a file showing which configurations were created and which failed.
CSV Format
Your file uses a single set of headers to describe two kinds of rows: configuration rows and product rows.
config_name,start_date,end_date,place_group_ids,phototype,upc,external_id,bb_guid
| Row type | Populate | Leave empty |
|---|---|---|
| Configuration row |
config_name, start_date, end_date, place_group_ids, phototype
|
upc, external_id, bb_guid
|
| Product row |
config_name and at least one of upc, external_id, bb_guid
|
Configuration columns |
-
config_nameis the key that ties a configuration's rows together. Every row sharing aconfig_namebelongs to the same configuration. - To include more than one place group or phototype on a configuration row, separate values with a pipe (
|). -
end_dateis optional. If left blank, the configuration runs until manually stopped or until it hits the 6-month maximum duration.
How the file is processed
- The entire file is validated before anything is created.
- A configuration is the unit of failure. If any row belonging to a
config_nameis invalid, that whole configuration and its product rows are skipped. Other valid configurations in the file are still created. - Product rows with a
config_namethat doesn't match any configuration row are treated as errors and don't block the rest of the file. - The upload button is disabled once clicked, until processing finishes. This prevents duplicate submissions.
Reviewing results
When processing finishes, you'll see a confirmation showing how many configurations were created and how many failed.
If any rows failed, download the returned file. It's your original CSV with an added errors column:
- Rows that processed successfully show a blank
errorscolumn. - Rows that failed show one or more specific error messages.
Bulk Upload Error Messages
If a row fails, the errors column tells you specifically why. If a row has more than one problem, all of them are listed, separated by a pipe (|).
| Issue | Error message |
|---|---|
Missing config_name
|
"config_name is required." |
Missing start_date
|
"start_date is required." |
Missing place_group
|
"place_group is required." |
Missing phototype
|
"phototype is required." |
start_date isn't formatted correctly |
"start_date must be in YYYY-MM-DD format." |
end_date is earlier than start_date
|
"end_date must be after start_date." |
| Place group doesn't exist in your account | "Place group '[value]' not found in your account." |
| Phototype doesn't exist in your account | "Phototype '[value]' not found in your account." |
| Product row has no identifier | "At least one product identifier (upc, external_id, or product_gsc_id) is required." |
Product row's config_name doesn't match any configuration in the file |
"config_name '[value]' does not match any configuration in this file." |
Same config_name used on more than one configuration row |
First occurrence: "Duplicate configuration rows for config_name '[value]'; no configuration was created." Later occurrences: "Duplicate configuration row for config_name '[value]'; a configuration for this name was already provided on row [n]." |
| Product row belongs to a configuration that failed | "Belongs to invalid configuration '[config_name]'." |
Rows with errors don't prevent the rest of the file from processing. Fix the flagged rows and re-upload just those configurations.
Configuration Restrictions
Limitation |
Details |
|---|---|
No Editing After Start |
Once a configuration is started, it cannot be edited. This is due to the backend calculations required. To make changes, create a new configuration and stop the old one. |
No Retroactive Data |
You cannot create a configuration to see past data. The system only processes mission responses that come in after the configuration starts. |
Mission Response Level Roll-UP |
Product presence is calculated at the mission response level. If multiple phototype are a part of the same configuration, results are compiled together rather than separated based on phototype. |
Managing Configurations
Before Configuration Starts (Scheduled Status)
While a configuration is in "Scheduled" status (start date is in the future), you can:
Add products individually by GUID
Delete products from the list
Modify place groups
Change photo types
After Configuration Starts
Once the configuration is active, no edits are allowed. If you need to make changes, you must create a new configuration with the updated settings and stop the old one.
Best Practices
Mission Structure Recommendations
Separate missions for different scene types: If you need separate product lists for shelves vs. coolers vs. floor displays, create different missions for each to get clear presence rates.
Combined product list option: If you only need to verify products are somewhere in the location (regardless of specific fixture), you can create one comprehensive product list.
Configuration Naming
Use clear, identifiable names to easily distinguish between configurations when you have multiple active. These names will be visible to mobile users.
Viewing Product Presence Data
The Product Presence Presence rate is calculated by counting how many products were expected and found to be available across all mission responses. The total count of found over the total count of expected is then used to calculate the rate. e.g., if a configuration has 10 expected products and there are 10 visits, the expected count is 100 of product-mission-response opportunities.
Location Level View
When viewing your locations, you can see the Product Presence rate displayed for each location. Click on a location row to access more detailed information.
What You Can See at the Location Level:
Mission responses that apply to that specific location
Overall presence rate for the location
Mission Response Level View
The mission response view provides the most detailed breakdown of product presence. The rate shown here is specific to that individual place and mission response.
On-Shelf Product List |
Off-Shelf Product List |
|
|
Grouping Options
You can group products by brand, brand family, or classification to better analyze your data. This helps users slice their data in a meaningful way.