Installing the Pixlee Magento 2 Extension

Get Your Pixlee API Keys

Before installing the Pixlee Magento 2 extension, you will need your API Key and Secret Key from https://www.pixlee.com.

1. First, log in to https://www.pixlee.com and click on the Settings button inside the top right hamburger menu.

(Alternatively, point your browser to https://app.pixlee.com/app#settings/account_settings while logged in).

The settings page should look like this:

2. Click on Pixlee API on the lefthand navigation bar.

From this page, record the values of Account ID, Account API Key, and Account Secret Key.

We'll need these later.

Install the Pixlee Magento 2 Extension

Magento extension installation instructions

Install the extension using one of the two below methods. Installing using composer is the recommended method.

Install extension using composer (recommended)

On your Magento server, run the following commands to install the extension using composer.

composer require pixlee/magento2
bin/magento module:enable Pixlee_Pixlee --clear-static-content
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean

Install extension in app/code

1. Download the extension Source code zip from https://github.com/pixlee/magento2/releases.
2. Extract the contents of the file downloaded in the previous step in your Magento 2 folder's app/code folder. Verify that the directory structure looks like <Your Magento 2 folder>/app/code/Pixlee/Pixlee.
3. Open up a command prompt. If you are using Windows, this can be done using Run (CTRL + R) and typing in 'cmd'. If your are using a OSX, open up the spotlight search using CMD + SPACE and type in 'terminal'.
4. Log into the Magento server and navigate to your Magento 2 folder using command prompt or terminal, and execute the following commands.

bin/magento module:enable --clear-static-content Pixlee_Pixlee
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean

Clear the Magento 2 Cache and Cache Storage

7. Open the Magento 2 Admin Panel and go to 'System' and click on Cache Management on the popup menu.

Click on Flush Cache Storage and after that Flush Magento Cache to clear the cache.

Configure the Pixlee Magento 2 Module

Before we can start using the plugin, we need to configure it.

Click on Stores at the left panel of the page and click on Configuration on the popup menu.

Select the website on which you'd like to install Pixlee, using the store view dropdown menu.

🚧

Note

If you keep the Store View as Default Config then the Pixlee Tab will not appear.

On the Navigation panel on the left, click on Pixlee and then Existing Customers. You should be redirected to the Pixlee Account Settings page.

Now it's time to use the keys we saved from pixlee.com in step 2.

Fill API Key and Secret Key with the values you recorded earlier.

Click Save Config on the top right corner of the page to save your Account Settings.

Exporting Products from Magento 2 to Pixlee

Conveniently, the Export Products to Pixlee button is right here!

Click it to complete the Pixlee Magento Extension installation.

You can export your Magento 2 products to Pixlee at any time from the Export Products to Pixlee button on the Pixlee Account Settings page.

🚧

Note

If you have ever changed the max_execution_time variable for Magento, please ensure that it is set to at least 3600 seconds (1 hour). The default should be 18000 seconds, which is fine to leave alone.

Embedding a PDP Widget on your Product Page

Assuming that all of your products are in sync with Pixlee, you can embed a PDP Widget on your product page by doing the following.

1. Go to http://pixlee.com, log in, and navigate to the Publish tab.

(Alternatively, point your browser to https://app.pixlee.com/app#publish while logged in).

2. Click the "Install Product Displays" and it should present you with a lightbox that looks like following.

3. Customize the widget as you wish. At the end, press the "Generate Embed Code" button and you'll be presented with an embed code. Note - We recommend that you leave the "Load Priority" setting to "Low priority" when customizing.

Copy the value for widgetId in the resulting code snippet. Fill in this value in the Widget ID field inside Admin > System > Configuration > Pixlee Account Configuration. This the same field that we skipped over in Step 10.

4. Now, to implement the Pixlee PDP widget, simply enter the value next to widgetId from the previous step in the PDP Widget ID field under the PDP Widget Settings section.

Click Save Config on the top right corner of the page to save your Account Settings.

With that, any product that has tagged photos in its Pixlee album should now have a widget gallery appear on its product description page.

To further customize, you can re-publish your PDP widget using Pixlee's Design Editor, and use that resulting widgetId instead!

5. Furthermore, if you'd like to customize the placement of the PDP widget, modify catalog_product_view.xml.

For example, in the Magento 2 sample store (Luma), it'd be in the following file:

$MAGENTO_ROOT/app/code/Pixlee/Pixlee/view/frontend/layout/catalog_product_view.xml

Where $MAGENTO_ROOT might be something like /var/www or /usr/share/nginx/html, depending on your installation.

Embedding a CDP Widget on your Category Pages

The first three steps are exactly the same as embedding a PDP widget as they only involve getting a widgetId from the Control Panel.

1. Go to http://pixlee.com, log in, and navigate to the Publish tab.

(Alternatively, point your browser to https://app.pixlee.com/app#publish while logged in).

2. Click the "Install Product Displays", and it should present you with a lightbox that looks like following.

3. Customize the widget as you wish. At the end, press the "Generate Embed Code" button and you'll be presented with an embed code. Note - We recommend that you leave the "Load Priority" setting to "Low priority" when customizing.

Copy the value for widgetId in the resulting code snippet.

4. Now, to implement the Pixlee CDP widget, simply fill in this value in the CDP Widget ID field inside Admin > System > Configuration > Pixlee Account Configuration > CDP Widget ID.

Click Save Config on the top right corner of the page to save your Account Settings.

With that, any product that has tagged photos in its Pixlee album should now have a widget gallery appear on its product description page.

To further customize, you can re-publish your PDP widget using Pixlee's Design Editor, and use that resulting widgetId instead!

5. Furthermore, if you'd like to customize the placement of the CDP widget, modify catalog_category_view.xml.

For example, in the Magento 2 sample store (Luma), it'd be in the following file:

$MAGENTO_ROOT/app/code/Pixlee/Pixlee/view/frontend/layout/catalog_category_view.xml

Where $MAGENTO_ROOT might be something like /var/www or /usr/share/nginx/html, depending on your installation.

Recurring Product Imports

The Magento 2 extension comes with a cron job that is used to import products to Pixlee on a daily basis. This will help ensure that product data is up to date in Pixlee and will allow new products created in Magento 2 to be imported daily.

📘

NOTE

Only the first website in your Magento 2 setup will have recurring imports, if you need multiple websites to have recurring imports, please reach out to the Pixlee team.

Also, you may need a member of your development team to help set up recurring imports.

Setting up Recurring Product Imports

To set up recurring product imports all you will need to do is run a compile command for your magento 2 setup.

Enter your magento 2 directory in a terminal session and run the following cli command:

$ bin/magento setup:di:compile

Afterwards you can refresh the cache with this command:

$ bin/magento cache:clean

Update the time and frequency at which products are imported to Pixlee

Once you have the recurring imports set up via the previous step, your magento 2 products will be imported on a daily basis at around 3am UTC. If you wish to change the hour in which the products are imported do the following:

1. go to the Pixlee extension code in your magento 2 setup and open this file: $MAGENTO_ROOT/app/code/Pixlee/Pixlee/etc/crontab.xml

2. To change the hour in the day at which the products are exported, change the 3 in the schedule tag to any hour you like:

<job name="export_cronjob" instance="Pixlee\Pixlee\Cron\ExportCron" method="execute">
    <schedule>1 3 * * *</schedule>
</job>

To change the minute within the hour in which the products exported, change the 1 to any minute you like. For further info on how you can change the scheduling of cron jobs, see this documentation: http://www.nncron.ru/help/EN/working/cron-format.htm

Testing and Troubleshooting

To test that everything was implemented correctly, we need to check two things -

1. Were all the products exported?
2. Are API calls being successfully made to the Pixlee API?

Were all the products exported?

Before testing, please make sure that the Pixlee Product Exports job has at least ran once. If you've already run the exports once, skip to step 3.

1. In order to run it manually. Open Admin Panel > Stores > Configuration > Pixlee > Existing Customers. Press the Export Products to Pixlee button to start the exports.

2. Login to Pixlee and navigate to Products under the Album tab. Alternatively, click this link..

3. You should see a list of products on this page.

5. Try searching for a few products on this page that you know exist in your catalog.

6. In case the list is empty or you were not able to search for a particular product, proceed to the next step. Otherwise, proceed straight to the next section i.e. Are API calls being successfully made to the Pixlee API?

7. There can be several causes of failure to export products so first, we need to find out the exact cause of the failure. The Pixlee Product Exports job logs the progress and all exceptions to the server logs. So the next step for us is to get the both Magento server logs and the PHP (Apache or equivalent) logs.

8. The Magento server logs are usually located at $Magento_Root$/var/log so navigate to that location and look for the file named pixlee.log.

9. For the PHP logs location, it depends on your setup. For example, if you're using Apache the logs should be in $Apache Root$/logs. We're looking for the file named php_error.log in this directory.

10. One of the most common issues that we encounter is a lack of allocated memory to the Magento or PHP/Apache server. Open the php_error.log file using your favorite text editor and search for a log entry similar to the following line

Allowed memory size of 33554432 bytes exhausted (tried to allocate 43148176 bytes) in PHP

11. If you found a similar looking error, please increase the allocated memory and run the product export job again.

12. Another common issue we encounter is a low setting for the max_execution_time. Look for a log entry similar to the following

Fatal error: Maximum execution time of XYZ seconds exceeded in ...

13. If you found a similar log entry please increase the max_execution_time setting inside your php.ini file to at least 3600. And then try exporting the products again.

14. If at this point you're still not able to see any products exported to Pixlee, please contact us at [email protected] and attach the both pixlee.log and php_error.log with the email.

Are API calls being successfully made to the Pixlee API?

API calls are made to Pixlee API when a customer adds something to their cart and when they buy something on your store. We need to make sure that these calls are being made at the right time.

1. Open your favorite browser and open a product page of your store. And click Add to Cart.

2. Open the pixlee.log file located at $Magento_Root$/var/log using your favorite text editor and scroll down to the very end.

3. There should be an entry beginning with AddToCart

4. If you found the AddToCart calls then your analytics were integrated correctly. If not, contact us at [email protected] and attach the pixlee.log file with the email.

5. Switch back to the browser and proceed to checkout and buy the product that you added to cart previously. Use a test payment method for the checkout.

6. When you reach the order confirmation page switch open the pixlee.log file again and ensure that you are viewing the latest copy of the file.

7. This time look for log entries beginning with CheckoutSuccess

8. If you do not see the CheckoutSuccess calls like in the screenshot, please contact us at [email protected] and attach the pixlee.log file with the email.

🚧

Disclaimer: Mobile Analytics

Based on the design of Magento2, user agents are not passed along the add to cart and conversion events. This means that there is no current ability to split between mobile and desktop conversion data.

RequireJS error on pages containing widgets

To verify that you are encountering this issue, do the following:

1. Open your website on your browser and navigate to a page where a Pixlee widget should appear.

2. Open the developer tools for your browser, navigate to the console tab and verify that you are seeing this error:

🚧

Note

The cause of this error is that pixlee.com only generates embed codes in plain HTML. Whereas the Pixlee Magento extension is compliant with RequireJS standards and expects Pixlee scripts to be only embedded via RequireJS. This problem can be resolved by creating a widget with these steps here instead of directly adding the widget embed code from pixlee.com. However, if you wish to keep the generated embed code, follow the steps below.

3. Find the generated embed code for the widget. It should look like this:

Here is a formatted version of the above code:

<div id="pixlee_container"></div>
<script type="text/javascript">
  window.PixleeAsyncInit = function() {
    Pixlee.init({apiKey:'YOUR_API_KEY'});
    Pixlee.addSimpleWidget({widgetId:YOUR_WIDGET_ID});
  };
</script>
<script src="//assets.pxlecdn.com/assets/pixlee_widget_1_0_0.js"></script>

4. Use the require function to change the embed code using these steps:

• Use the require function and add the asset.pixlee.com url as a parameter.
• Move the JavaScript code in the window.PixleeAsyncInit function to the require function's callback.
• Call the Pixlee.resizeWidget() function at the end of the callback.
• The new code should look like this:

<div id="pixlee_container"></div>
<script type="text/javascript">
  require(['https://assets.pxlecdn.com/assets/pixlee_widget_1_0_0.js'], function() {
      Pixlee.init({apiKey:'YOUR_API_KEY'});
      Pixlee.addSimpleWidget({widgetId:YOUR_WIDGET_ID});
      Pixlee.resizeWidget();
    }
  );
</script>