Integrating your Product Catalog using XML files is a reliable and efficient way to keep your product data synchronized with Insider One. This method simplifies managing large catalogs and ensures that recommendations and campaigns always reflect the most up-to-date product information.
How product information is collected
With XML integration, product information is collected directly from an XML file that you host. This file contains structured product data with all the attributes Insider needs to deliver accurate and up-to-date campaigns. Insider periodically fetches the XML file from the provided source URL and automatically updates the Product Catalog based on the latest data.
Each XML file must include a primary product element (for example, <item> or <product>), with nested tags that define product details such as item ID, title, price, stock status, and category. During setup, these tags are mapped to Insider’s product attributes so the system can correctly interpret and process your catalog.
Insider supports multiple XML formats to accommodate different catalog structures:
Criteo XML Format
Designed for advertisers and retailers already exporting product data to Criteo. This format follows a standardized tag structure, allowing for faster setup and attribute mapping.
Google Merchant XML Format
Commonly used by ecommerce businesses integrated with Google Merchant Center. Insider can automatically recognize and map attributes that follow Google’s catalog conventions.
Custom XML Format
Provides full flexibility to define your own XML structure and tags. This option is ideal if your catalog includes unique data points or custom fields. Each tag can be manually mapped to the corresponding product attribute in Insider.
Using XML integration allows Insider One to continuously collect, process, and refresh your product data with minimal operational effort.
Requirements before starting
Before starting your XML integration, ensure the following prerequisites are met:
Plan product attributes in advance
Identify all default and custom product attributes required for your selected Product Catalog Feed type. Create any necessary custom attributes from the Product Attributes page before integration.
Prepare a complete XML file
Your XML must include all required attributes for your feed type. Missing required attributes may prevent the catalog from being processed correctly.
Host the XML at a stable URL
Insider One retrieves product data from the source URL you provide. The XML file must be continuously accessible and reliably hosted.
Validate XML structure
Ensure your XML follows a consistent and well-formed structure. Each product entry should include an item ID, title, price, stock information, and all other required attributes defined by your feed type.
Meeting these requirements ensures a smooth XML integration and reliable synchronization of your Product Catalog with Insider One.
Step-by-step integration
Follow the steps below to integrate your XML Product Catalog with Insider One.
1. Plan your product attributes
Begin by reviewing the default product attributes and deciding which ones you will use.
Review the required product attributes for your selected Product Catalog Feed Type. You can find the full list in the Product Attributes article.
Review your existing XML file and verify whether each required attribute is already included.
Identify any custom product attributes you will need in addition to the default ones.
2. Create Custom Product Attributes
Before enabling the XML integration, create all required custom attributes.
Navigate to Components > Product Catalog Management > Product Attributes.
Create the custom product attributes identified in the previous step.
3. Enable XML Integration
Navigate to Components > Product Catalog Management > Catalog Settings.
Open the Integration Settings tab.
Select XML as the integration method and click Save.
4. Navigate to the XML Integration page
Go to Components > Product Catalog Management > XML Integration.
5. Create a new integration
Click Create to start a new XML integration.
Enter a clear and descriptive name (for example, Product Catalog – EN – 2023).
Select the appropriate XML format type.
6. Set up Source URL and Locale
Enter the source URL where the XML file is hosted.
Select the locale for the Product Catalog.
If you manage multiple locales or stores, create separate XML integrations for each one.
7. Define product tags
Product tags identify the XML element that represents a product record.
Specify the tag used to define a product block (for example, <item> or <product>).
Ensure the selected tag clearly encapsulates all product-related fields so they can be parsed correctly.
8. Match Product Attributes
Before activating the integration, map XML fields to Insider product attributes.
Exact Match: Use when the XML field name directly matches an Insider One attribute.
Custom Match: Use when the XML field does not match a predefined attribute. In this case, define a custom JavaScript expression to map the XML field to a custom product attribute in Insider One.
Custom Match Examples:
Attribute | XML | Custom Match JavaScript |
|---|---|---|
In Stock | <g:availability>in_stock</g:availability> | obj => obj["g:availability"] == "in_stock" ? 1 : 0 |
Price | <g:price>133 USD</g:price> | obj => obj["g:price"].split(" ")[0] |
Category | <g:google_product_category>Home & Garden > Decor > Clocks</g:google_product_category> | obj => obj["g:google_product_category"].split(" > ") |
9. Set synchronization period
Choose how often you want to fetch the latest XML file and update the product catalog. The synchronization interval can be set anywhere from 1 hour to 5 days. Make sure this matches the frequency at which your internal XML file is updated.
After configuring all the settings, click Save and Activate to make the integration live.
Out-of-Stock Management
When configuring XML integration, you can control how stock information is handled by choosing one of the following options:
Send All Products with Stock Status
When this option is selected, the XML file includes both in-stock and out-of-stock products. Products that are not present in the XML file will retain their existing stock status in Insider One.
To use this option, keep the Send Only In-Stock Products toggle disabled.
Send Only In-Stock Products
When this option is selected, only products marked as in stock in the XML file are processed. Any products that are not included in the XML file are automatically marked as out of stock in Insider.
To use this option, enable the Send Only In-Stock Products toggle.
Manage XML Integrations
Once your XML integration is live, you can manage it from Components > Product Catalog Management > XML Integration.
You can perform the following actions:
View Integration Details: Review the source URL, locale settings, and the list of mapped product attributes.
Edit Integration: Open the integration in edit mode to update configuration details when changes are required.
Activate or Deactivate Integration: Enable or disable an integration as needed. By default, newly created integrations are set to Active. You can switch an integration to Passive at any time to prevent it from affecting the Product Catalog.
Only one XML integration can be active per locale or store at a time. Additional integrations can remain passive for future use.
Validation and Error Handling
To prevent invalid or incomplete data from entering the system, Insider One applies an XML validation process. Before activating a new XML integration or modifying an existing one, the XML file must be successfully validated.
Validation Statuses:
Active: The integration is active, and the XML file is being processed.
Passive: The integration is inactive but can still be edited and validated.
Validation Pending: The XML file is currently undergoing validation.
Ready to Activate: Validation completed successfull,y and the integration can be activated.
Validation Failed: Errors were detected in the XML file. These issues must be resolved before activation.
System Error: A system-level issue prevented validation. Contact the Insider One team if this status persists.
Key considerations
Multiple XML Integrations: You can create multiple XML integrations per locale or store, but only one can be active at a time.
Synchronization Frequency: Choose a synchronization interval that matches the frequency with which your product data is updated.
Missing Required Fields: Products missing required attributes (such as item_id or in_stock) are ignored during processing.
Custom Attributes: All custom product attributes must be created and configured in the Product Attributes section before they can be used in XML mappings.
XML integration provides a scalable and reliable way to keep your Product Catalog synchronized with Smart Recommender. By supporting automated updates, flexible data structures, and multi-locale setups, it ensures users consistently receive accurate and personalized product recommendations.