HomeEngagementContentDiscoveryOther Resources

Magento plugin

Suggest Edits

Plugin overview

The plugin's primary goal is to enable faster and easier integration of your Magento 2 store with Bloomreach Engagement so that you can leverage our cross-channel automatization, deep personalization, and store optimization features faster. It comes with some key integrations out of the box, with possible changes needed depending on your level of customization of the Magento platform.

The plugin provides several data feeds, or “data flows” - streams of data from Magento, for standard data objects out of the box:

  • Customer Data Feed
  • Purchase Events Feed
  • Product Feed
  • Basic Web Tracking
  • Cross-device Identity Resolution for Logged-in Visitors

Correct configuration allows you to start deploying automation immediately, triggered campaigns, and web personalization that will help you grow your store's revenue.

Features

The data feeds run an initial import when the plugin is activated and then near real-time updates. These run every 15 minutes by default. The imports include:

Customer data feed - Customer profiles and attributes, as follows:

  • customer_id
  • personal information (email, name, phone number)
  • newsletter subscription flag (can be added if present)
  • additional custom attributes can be added by code

Purchase feed - Tracks all orders made by the customers when they are placed. Guest orders are also tracked under the email address. Additional custom attributes can be added by code, but the default ones are:

  • purchase_id
  • total_price in the reference currency
  • local_currency and total_price_local_currency for other currencies
  • purchase_item with product metadata (title, categories)
  • discount values and percentages

Products feed - Products and Variants catalogs. Both of these can be populated. Features near real-time item deletion via Catalog API. Additional custom attributes can be added by code, but the default ones are:

  • identifiers for product_id, variant_id, SKUs
  • metadata, including labels, categories
  • full URLs to images and product detail page
  • stock availability (stock_level)
  • online listing (active)

The plugin comes with front-end tracking of customer behavior on your Magento storefront that includes basic web tracking of events, such as view_item, cart_update, and order placed ​​automatic injection of Bloomreach Engagement JS SDK into the website HEAD, and customer identification (when logged in). The tracking can be extended by code.

Any previously mentioned events will be tracked and added to the Queue and later sent to Bloomreach Engagement. The queue is processed by a configurable cron that is regularly running based on the plugin’s configuration.

The data is synchronized with Bloomreach Engagement via REST API, using CSV files, for the initial import, and API endpoints, for updating the customer and product information.

For the importing process, all the data is grouped in batches in order to have a smaller amount of requests.

Additional features

There is a number of possible additional features that come with

  • Customizable schedule of jobs* (affects updates frequency)
  • Customizable retention of data in queues
  • Customizable retention of generated CSV files
  • Application Logs for operations on the Magento side

How does it work

The plugin is available at Magento’s marketplace and on Github.

First, the plugin shall be installed by your IT team according to the installation manual that we have prepared. The following configuration will require work on both the plugin and the Bloomreach Engagement side.

After correct configuration, the plugin will run the initial import of your historical data, and then subsequent near real-time updates are scheduled.

Initial imports

  1. New data updates are pushed to the queue.
  2. Scheduled job flushes the queue into CSV files.
  3. An Import Trigger API call triggers individual imports with a path to a CSV file.

Near real-time updates (Default: every 15 minutes; configurable by Magento admin)

  1. New data updates are pushed to the queue.
  2. Scheduled job flushes the queue and sends the updates to the Tracking API.

The plugin is fully compatible with the latest stable versions for Magento 2.3 and 2.4, including Open Source (former Community) and Commerce versions (Enterprise). Versions older than 2.3 are not officially supported; however, the plugin can be helpful as a good starting point for custom integrations.

Setup in a nutshell

(A) Install and customize the Magento plugin.
(B) Configure Engagement API keys for Private access with proper permissions

  1. Create Engagement project with the following customer IDs:
  1. Add Engagement API keys for Private access with the following permissions:
  • Customer properties > enable all Set
  • Events > enable all Set
  • GDPR > Anonymize customer enable
  • Catalogs > enable Update catalog item, Delete catalog item
  • Imports > Allow import trigger enable

📘

Imports and Catalogs

Imports and Catalogs must be pre-created manually - a dummy CSV file is provided by the plugin and hosted on the HTTPS address of the Magento server (see below)

(C) Configure the Magento plugin

  1. Go to Stores > Configuration > Bloomreach engagement > Settings.
  2. Expand General and adjust:
  • Enable Integration: Yes
  • Set credentials
  • Save changes
  1. Expand Imports and click Generate dummy import files, then save the list of files.
872

(D) Configure the plugin in the Bloomreach Engagement app

  1. Go to 'Data & Assets > Imports'.
  2. Create new import of Customers:
  • Run an import from the URL (paste the URL for the Customer feed dummy file)
  • Name the import as "Customer feed"
  • Map email_id and customer_id by enabling the mapping of multiple IDs - uncheck IDs from importing as customer properties
  • Finish it as a single-run import
  1. Create new import of Events:
  • Set the event type to "purchase"
  • Run an import from the URL (paste the URL for the Purchase feed dummy file)
  • Name the import as "Purchase feed"
  • Map email_id and customer_id by enabling the mapping of multiple IDs - uncheck IDs from importing as customer properties
  • Finish it as a single-run import
  1. Create new import of Events:
  • Set the event type to "purchase_item"
  • Run an import from the URL (paste the URL for the Purchase feed dummy file)
  • Name the import as "Purchase Item feed"
  • Map email_id and customer_id by enabling the mapping of multiple IDs - uncheck IDs from importing as customer properties
  • Finish it as a single-run import
  1. Create new import of Catalog
  • Set the catalog name to "products"
  • Run an import from the URL (paste the URL for the Product feed dummy file)
  • Name the import as "Products feed"
  • Change to "Product catalog"
  • Enable Searchable (indexing) on additional columns based on use cases; the recommendation is: title, description, sku, rating
  • Finish it as a single-run import
  1. Create new import of Catalog
  • Set the catalog name to "variants"
  • Run an import from the URL (paste the URL for the Variant feed dummy file)
  • Name the import as "Variants feed"
  • Change to "Product catalog"
  • Enable Searchable (indexing) on additional columns based on use cases; the recommendation is: title, description, sku, product_sku, rating
  • Finish as single run import
  1. Go to Data & Assets > Data manager.
  • Set the fields as Private for these Customer properties: first_name, last_name, email, phone
  • Save changes
  • Set fields as Private for these Event properties: session_start: cookie, ip; first_session: cookie, ip; session_end: cookie, ip; merge: requested_ids, final_external_ids, original_external_ids
  • Save changes.
    (E) Configure the Magento plugin:
  1. Insert Import IDs from the Engagement app.
  2. Insert Catalog IDs from the Engagement app.
  3. Enable Exponea JS SDK: Yes.
  4. Save changes.
  5. And click Run initial import.

Use case examples

We aim to provide you with all the necessary data for the majority of StartRight use cases. However, the real selection of use cases will depend on the integration and what data are available in your Magento.

Here are some example use cases that should work out of the box:

  • Welcome Flow
  • Traffic Analytics Dashboard
  • Email Performance Dashboard
  • Birthday & half-birthday campaigns
  • Abandoned Cart Flow without Product Personalization
  • Post-purchase NPS survey email
  • Lookalike targeting based on CLTV and loyalty
  • Conversion Dashboard
  • Abandoned Browse Flow
  • On-Exit Banner with the Last Viewed Items
  • Retention Dashboard
  • Customer Lifetime Value Dashboard (+ RFM Segmentation)
  • Product Analytics Dashboard
  • Watchdog automatic restock alert
  • Abandoned Cart Flow with Product Personalization

Happy path tests

All of the following tests should be passed when the integration is correctly set up (correct project setup, API keys permissions, Imports, Catalogs, cron jobs active, storefront tracking enabled).

Initial customer import
Expected behavior: After the import is finished, Customers are imported with proper IDs (email_id, customer_id) and properties.

Initial purchase import
Expected behavior: After the import is finished, events "purchase" and "purchase_item" are imported with proper IDs (email_id, customer_id) and properties. Guest orders are tracked under email_id. Orders of registered customers are tracked under customer_id. All events have status success and a timestamp corresponding to when the order was placed.

Initial catalogs import
Expected behavior: After the import is finished, catalogs of "products" and "variants" are imported with items. All items have correct IDs, titles, categories, and stock levels, plus active status and full URLs.

Near real-time customer updates
Expected behavior: Customer attributes are updated every 15 minutes by triggering Customer import with changes. Changed customer data is updated. Deleted customers' personal information is anonymized. If there is a failure on import, it is retried. If there is a delay and older customer changes are imported after newer changes, older changes are ignored based on the last modified time. All customer changes after initial import are transferred with this method (meaning there is no data inconsistency/gaps).

Near real-time purchase updates
Expected behavior: Newly placed orders are imported every 15 minutes as events "purchase" and "purchase_item" by triggering purchase feed imports. If there is a failure on import, it is retried. All newly placed orders after initial import are transferred with this method, meaning there is no data inconsistency or gaps.

Near real-time catalog updates
Expected behavior: Changes in products are imported every 15 minutes. Product updates are updating both "products" and "variants" catalogs. Product deletes are deleting items from "products" and "variants" catalogs. All catalog changes after initial import are transferred with this method, meaning there is no data inconsistency or gaps.

Real-time website behavior tracking
Expected behavior: JS SDK is injected into the storefront and initialized. Visitors are identified with a customer_id when they are logged in.
Events "view_item" are tracked on product detail pages, including product metadata. Events "cart_update" are tracked when there are any changes to the shopping cart contents. Events "order" and "order_item" are tracked from the front end on the Thank you page when a guest or registered customer places an order.
When done by a logged-in visitor, website tracking is tracked to an identified customer's profile by cookie and customer_id. Website tracking is tracked to an identified customer's profile by cookie and email_id when done by a guest after they place the order.

Updated 4 months ago