Implementing Dynamic Yield on Magento 2.x – Dynamic Yield Knowledge Base

The Dynamic Yield Magento integration provides quick and seamless integration with Dynamic Yield and enables automatic implementation of the Dynamic Yield e-commerce solution that includes:

Dynamic Yield tracking script implementation
Context API implementation
e-commerce events implementation
Product feed (catalog) export

The Magento implementation is compatible with both the Enterprise and the Community editions, and supports the following event types:

Purchase
Add to cart
Signup
Login

Newsletter subscription
Add to wishlist
Remove from cart
Sort items

Filter items
Change attribute
Promo code entered
Search

Note: Bundled products are not supported and are not migrated to Dynamic Yield.

Integration requirements

The following are assumed to be true regarding your Magento environment for the integration. If any of the following assumptions are false, speak to your Customer Success Manager to determine whether this implementation method is supported for your environment.

Your Magento site is based on a single data feed that will map to one Dynamic Yield section. The section can manage one storefront or multiple translations of the same storefront.
If you have multiple store views of any type other than translation of the same store, create a section and product feed for each one, and then sync them manually, following the procedure described in Product Feeds.
There are fewer than 150,000 products in your product feed. If you have more than that, disable the feed synchronization in Magento and upload the feed manually. For details, see Product Feeds.
The store theme has not been heavily customized in a way that would make the DOM element data difficult to access using JavaScript.
The Magento core code has not been modified directly or extended incorrectly.
If you manage stock availability per locale using a plugin in Magento, your feed must be manually synchronized to Dynamic Yield. For details, see Product Feeds.

Mapping store views to Dynamic Yield sections

The following are the steps you must complete to map your store views to Dynamic Yield:

Step 1: Create your section in Experience OS

A section in Dynamic Yield Experience OS represents your store's site in our system. Each section has an associated product feed, which is your product catalog. You'll configure the sync of the catalog/feed in the following steps.

To create the section, go to Experience OS and follow the directions provided in Managing Sections.

Step 2: Create your product feed file

The product feed is a file that contains your product catalog (all your products, with product metadata). First, you must first create a file to upload to an S3 bucket, to sync with the Dynamic Yield product feed. Follow the instruction in the Create the file section of the Product Feed article. Then, to sync the product feed, you'll create an S3 bucket as described in the next step.

Step 3: Sync your product catalog with Dynamic Yield

A synced product feed enables capabilities like recommendations, segmenting based on product engagement, social proof tactics, and more.

To enable the sync, you must enter the AWS S3 access and secret keys in the Configuration step.

Get your AWS S3 credentials

In Experience OS, navigate to Assets › Data Feeds.
Do one of the following:
- If you already have a product feed, go to your feed and click Edit.
- If you don't yet have a product feed, click Add New to create one.
In the Feed Source, select Sync a file via Amazon S3.
Do one of the following:
- If you're editing an existing product feed, click Generate Credentials.
- If you're creating a new feed, click Create a bucket.

Step 4: Configure the Dynamic Yield Site ID in your Magento admin panel

This step is part of the Configuration procedure described later in this article. It's important that you copy your Site ID from Dynamic Yield to complete this step

Installing the Magento extension

Go to the Magento 2 root in a command prompt and enter the following command:
```
cd <magento2-root> 
```

Add extension repository to composer config using the following commands:

composer config repositories.dynamic-yield/integration vcs 
https://github.com/DynamicYield/dy-magento-integration

Require extension using composer with the following command:
```
composer require "dynamic-yield/integration" --update-no-dev
```
This can take up to 10 minutes
Change directory to Magento 2 bin directory, so you can enable the extension as follows:
```
cd bin/
```
Make sure that the module has been successfully required by composer typing following commands in command prompt:
```
php magento module:status
```
This should return the following:
```
List of disabled modules:
DynamicYield_Integration
```
Enable maintenance mode by typing following commands in command prompt:
```
php magento maintenance:enable 
php magento cache:clean
```
Enable module by typing following commands in command prompt:
```
php magento module:enable DynamicYield_Integration
```
You should receive a message indicating the module has been enabled in the command prompt.
Make sure that the enabled modules are properly registered by typing following commands in command prompt:
```
php magento setup:upgrade --keep-generated
```
Deploy module static view files by typing following commands in command prompt:
```
php magento setup:static-content:deploy
```
Flush Magento 2 cache storage, by typing following commands in command prompt:
```
php magento cache:flush
```
Disable maintenance mode by typing following commands in command prompt:
```
php magento maintenance:disable
```
If you are using versioning system such as “Git”, commit these changes to your project repository by typing following commands in command prompt:
```
cd ..
git add composer.json composer.lock && git commit -m "Added dynamic-yield/integration module" && git push
```

Important notes:

If you use Varnish or similar caching solutions, ensure the Dynamic Yield blocks are not cached. In certain cases, hole-punching might be necessary.
If you're using a custom template and the template uses HTML classes other than the default ones, you must adjust those fields so that the Dynamic Yield integration can work properly, as shown in the Advanced Settings section of this article.

Configuration

In the Magento admin, go to Stores › Configuration.
Open the Dynamic Yield › Integration.
In the Settings section, fill in the fields:
- In the Site ID section, enter your Dynamic Yield site ID.
  - This is a store view level configuration, which means that it is possible to set different Site ID for each store view.
  - Product feed uses default value and remains a global configuration.
  - If you have multiple Store Views representing anything other than multiple translations of the same store, see the previous section, Mapping Store Views to Dynamic Yield Sites.
- In the Access Key ID, enter the value provided by your Customer Success Manager. This gives the extension access to your AWS S3 bucket. This configuration is global and therefore affects all stores and store views in this instance of Magento.
- Enter the Secret Access Key provided by your Customer Success Manager. This gives the AWS bucket access to the feed storage. This configuration is global and therefore affects all stores and store views in this instance of Magento.
In the Product Catalog Sync section, fill in the fields:
- Enable Product Feed Sync: This should be enabled, unless your feed is not standard and must be manually synchronized (see Integration requirements). If you disable the sync, you don't need to configure any other settings in this step.
- Sync rate: Export feed. Sync rate configurations determine how often you want the feed to be updated on Dynamic Yield.
- Product Attributes: Enhance your personalization capabilities by syncing up to 10 additional key product attributes (mandatory attributes are already selected). Note that you won't be able to deselect attributes after sync.
- Used Product Attributes: List of selected attributes. To remove an attribute, click it and then click Save.
  
  Note: You should not deselect an attribute after the feed has synced. Contact your CSM for additional information
- Exclude Categories: Categories that will be excluded from the product feed column called “categories”. These categories will be reported in the column “keywords”. This is designed for temporary categories, such as “winter sale”, which do not represent the main category tree but are still valuable. If excluded, these categories will still be reachable via the keywords column.
- Category Trees: Define a root category for each store scope. Leave empty if all trees are included in all store views.
- Debug Mode: Enable product feed debug mode. The logs are written to a file dyi_feed.log.
  
  All configurations are global and apply to all stores and store views in this instance of Magento.
Use the Custom Locale section to configure page context for each translated version of your site. For more details, see Validating Multi-Language Sites.
Expand the Integration Type section and complete the following settings:
- Enable Dynamic Yield Europe Account: Set this field to “Yes” to enable the Dynamic Yield Europe account. This setting will adjust the tracking script URLs and product feed upload URL. No other configuration is necessary.
- Enable CDN integration: If you choose “Yes” or “European” an input field to write your own CDN URL is shown (choose “Yes”). If “European” is chosen the product feed bucket endpoint URL is changed.
- CDN URL: You can write your custom CDN URL that will be used to include the tracking scripts.

Advanced settings

If you're using a custom template and the template uses HTML classes other than the default, you need to adjust those fields so the Dynamic Yield integration can work properly. For Magento versions 2.2 and higher, the Developer tab and options are only available in Developer Mode.

Go to System › Configuration › Advanced › Developer in the admin panel.
Expand the Dynamic Yield Integration section, and configure the following as needed:
- Triggers: These configuration values expect a CSS selector (element, class, id) of the element that will trigger the action. An event listener is attached to this element. In case the DOM element is not found the event will not be attached and that particular event will not be tracked. To find the appropriate selector inspect the source code of the page and find the element that is responsible for triggering the filter/sort/change functionality. This can be any element (div/select/a/span). Usually just clicking on the element to inspect source is enough to find it, but sometimes it is more convenient to select the parent or child element.
- Type and Value: After you find the trigger element, you must next extract 2 values – type and value (filter type: Size, filter value: Green). To extract these you need to configure the Value and Type configuration fields. These fields show the DOM structure relative to the trigger element and are used to extract the type and value data. The structure (Type and Value) configs expect a JSON type string where keys are functions and values are function parameters. Any function that is available in the given scope can be used in the structure. Here is an example:
- Filter can have multiple types: Attribute, text-based swatch, image-based swatch, and so on. Therefore, there are multiple configuration values for each type. Fill in necessary fields according to your requirements. If you don't use a particular type of filter you can leave the configuration as-is or leave the field empty.

Configuration is store scope so it is possible to set different selectors for each store view.

Validation

It's important to validate that your script, page context, data feed, and events have been set up properly. To do this, use the Implementation Status Dashboard and the Web Implementation Helper.

See Validating Your Web Implementation for help with validation.

If you have multiple storefronts representing different translations of your site, see the Validating multi-language sites section of this article. If you have any issues with the Purchase event, see the Troubleshooting Purchase events section. If you can't validate your product feed, see the Troubleshooting your product feed section.

Validating multi-language sites

If you have multiple storefronts representing different translations of your site, it's important to validate that the page context is properly aligned for each site. This is in addition to the standard page context validation procedure.

Go to one of your websites and open the browser console.
Locate the page context by searching for DY.recommendationContext.
Verify that the lng parameter is aligned with the language of the page.
Repeat this procedure for each translated version of your site.
If you find one or more lng parameters that aren't aligned with your site, you can update it in the plugin settings.
1. Go to System › Configuration › Advanced › Developer in the admin panel.
2. Expand the Dynamic Yield Integration section.
3. Set the Enable Custom Locate setting to true and use the drop-down list to select the correct language for the Store View that is currently selected. Repeat for every Store View.
4. If the drop-down list does not have the correct language setting, set Set Custom Locate to true and specify the language string in the Custom Context Store Locale field (e.g. de_DE).

Troubleshooting Purchase events

The integration uses default Magneto events that work with default Luma and built-in modules. So, if you use a third-party payment/checkout module, you need to make sure that these events are triggered (or add observers to your custom events) during place order:

Magento1 – sales_order_place_after
Magento2 – checkout_onepage_controller_success_action

Troubleshooting your product feed

If you could not successfully sync your product feed, use the following checklist to verify that all required settings are configured before contacting customer support.

Verify that the Enable Product Feed Sync setting is enabled in Magento. For details, see the section Mapping store views to Dynamic Yield sites.
Check the Site ID, Access Key, and Secret Key settings and make sure they are correct.
Verify that cron is running on your Magento site.
Verify that the feed file is created on the server: {magento_root}/var/dyi_export/productfeed.cs

FAQs

Does the integration support Varnish full-page caching?

Yes, the integration works with Varnish full-page caching. If Varnish or a similar caching solution is used, make sure that Dynamic Yield blocks are not cached. In certain cases, hole-punching might be necessary.

If I use a third-party search extension, will the search event work?

In most cases, yes. However, if the search extension doesn't follow the Magento default built-in class hierarchy, contact us to create a custom solution for you.

The Sort event isn't working. What should I do?

If you use a custom template, there might be some issues with the Sort event, as it's strictly for default Magento templates. Contact us to create a custom solution for you.

The Change attribute event isn't working. What should I do?

This integration is designed to work with default Magento functionality. Are you using any third-party extensions for product page attributes? If so, contact us to create a custom solution for you.

One of the listed events isn't working. What should I do?

This integration is designed to do the least possible harm to any other extensions, but in some cases, there might be conflicts that can cause issues for some events or some other functionality. If this is the case, contact us so our support team can evaluate and fix this issue.

I’m getting a message “DynamicYield Integration: Products missing mandatory attributes. Details: dyi_skipped_products.log”:

Products are validated to ensure that all of the mandatory attributes are set. If you receive this message, it means that some products were skipped during the product feed export. The skipped products are listed in the dyi_skipped_products.log.