Magento V1.9 Plugin Installation and Configuration

Set up the Magento plugin.

Magento Plugin Installation and Configuration

Purpose of this Document

This document explains how to install and configure the Magento Plugin to integrate with CitrusAd. It is important that you read this document to the end, and that you understand how to avoid module conflicts in the Magento Plugin.

Requirements Magento 1.9.x

Installation of the Magento Plugin

To install the extension in Magento:

  1. On your Magento admin panel, go to System -> Magento Connect -> Magento Connect Manager

  2. Choose the citrusad-[version_num].tgz file and click on "upload".

NOTE: You can also copy the plugin source code into your Magento installation.

NOTE: It is possible that you will have to modify the plugin code in order to use the Citrus Plugin. If you experience conflicts, see the section "Dealing with Conflicts" below in this document. There is a high likelihood that there will be a conflict between your customisations of the Magento instance and the Citrus Plugin. If any of your existing customisations touch list.phtml or Mage_Catalog_Block_Product_List, then you must refer to the "Dealing with Conflicts" section of this document.

Set up the Citrus Plugin

General settings

  1. After the installation, go to Magento admin panel -> System -> Configuration, and click on CITRUS INTEGRATION -> General Setting.

  2. Enable the plugin in the Magento admin panel. (Select "Yes" in the dropdown menu.)

  3. Input your Team Id and Api Key from Citrus and select the host. NB: To find out your Team Id and Api Key, log in to the Citrus Client and go into the Integration Settings from the drop down list in the top right corner.

  4. Click "Save Config".

  5. After clicking "Save Config", you can sync products, customers, and orders and enable ads and banners and add widgets.

Synchronization settings

  1. Go to Magento admin panel -> System -> Configuration, and click on CITRUS INTEGRATION -> Synchronization Option on the left sidebar.

  2. Ads(display ads) and Banners can be switched ON/OFF separately.

  3. Enable synchronization for both Customer/Orders and Products and set sync modes as Real-time.

  4. Click Save Config.

  5. Click the buttons Add all customers to queue, Add all orders to queue and Add all products to queue.

  6. Now that we have all the customers, orders, and products staged in the queue, go to Magento admin panel -> Citrus -> Queue List, select the items to submit, select sync and click Submit so that they are synced to Citrus.

Prerequisites for Setting Up Banners Before installation, you must have done the following:

  • Contact Citrus to set up a Content Standard.

  • Configure the page specified for the Citrus Banner Widget (this means that you must set up CMS Widgets in Magento).

Configuring Pages to Include the Citrus Banner Widget

  1. Navigate in a web browser to your Magento Admin Console.

  2. Hover over CMS in the header menu.

  3. Select Widgets in the drop-down menu.

  4. Click Add New Widget Instance in the top-right of the window.

  5. In the "Type" dropdown, select Citrus Banner Widget.

  6. In the "Design Package/Theme" dropdown, select your preferred theme (this part is up to you).

  7. Click Continue.

  8. In the "Widget Instance Title" field, provide a unique name for this widget instance.

  9. Click the Add Layout Update button.

  10. In the "Display On" dropdown, select the kind of page on which you want to include the Citrus Banner Widget.

  11. Click "Save and Continue Edit" in the upper-right part of the New Widget Instance page.

  12. Hover over Citrus in the header menu.

  13. In the dropdown, select SlotId.

  14. Click Add New.

  15. In the Page Type dropdown, select the banner page type. If "Category Pages" or "CMS Pages" is selected, specify one or more page Ids by CTRL+Click-ing on the page IDs.

  16. In the "Slot Id" field, type in the slot id that matches the slot id specified in the content standard.

  17. Refresh the cache by navigating to System-> Cache Management -> Flush Magento Cache and clicking on Flush Magento Cache.

Usage Now that Citrus Magento Plugin configuration is complete, set up some display ad campaigns and some banner ad campaigns.



There are conflicts when two (or more) modules rewrite the same class. In that case, the class is overwritten by one module and the rest of the modules will not work properly. In some cases this can have a fatal impact on your platform.

Detecting Conflicts

Before you install the Citrus Magento plugin, make sure that there are no conflicts between your installed plugins and the Citrus Magento plugin. This can be done by checking the content in the "config.xml" files on all installed modules in your platform. Alternatively, you can use the Alekseson Modules Conflit Detector tool module to help you detect the conflicts:

​ .

If there is no conflict, the Magento plugin begins working immediately.

Dealing with Conflicts

If there are conflicts between the plugins, then you must resolve the conflict in order to use the Magento plugin. You can use

  1. Merging - merge the code from one conflicting file into another and switch off the rewrite config.xml in one of the files


  1. Class inheritance - switch off the rewrite in one config.xml and then make the conflicting extension PHP file extend the other extension


  1. both

Which of these options you choose depends upon the nature of your conflict.

In the Citrus plugin, the class Mage_Catalog_Block_Product_List is overwritten with the class Citrus_Integration_Block_Product_List.



The Citrus_Integration_Block_Product_List class overrides _getProductCollection() and adds two new methods:

getAdResponse() and


If your plugins do not override the same methods, you can use class inheritance and make the class Citrus_Integration_Block_Product_List extend your class or vice versa and then switch off the corresponding <rewrite>. If you want to use merging in this case, you must move the logic in the conflicting class to the one to which you want to merge and switch off the corresponding <rewrite>.

If your plugins override the same method as ours, you might need to use merging in this case with or without class inheritance. You need to make sure the logic and functionality from both plugins is implemented correctly. This requires understanding of the code and programming skills.

Click and impression functionalities are implemented in Javascript, which depends on the data in list.phtml. If your plugins have modified this file, you probably need to merge our logic with yours in this file as well.

Configure list.phtml If your theme overrides the file base/default/template/catalog/product/list.phtml file, you must make the following modifications to the list.phtml file in your theme directory.

Note: These instructions are generic. Depending on your theme, you might have to change these examples.

  1. Get the citrus_ad_id for each product in the collection.

<?php foreach ($_productCollection as $_product): ?>
<?php $citrus_ad_id = $_product->getCitrusAdId(); ?>
  1. Add citrus_ad_id to each product's LI element.

<li class="item<?php if (++$_iterator == sizeof($_productCollection)): ?> last<?php endif; ?><?php if(isset($citrus_ad_id)): ?> citrus-ads" data-id="<?= $citrus_ad_id ?> <?php endif; ?>">>

Here is example output:

<li class="item first citrus-ads" data-id="display_8ELknUfpR1bZ1XoY4v6Yv5LWuIcwMDAwMDAwMDAxNTA3Ng== ">
  1. Add the badge immediately after the product image.

<?php if(isset($citrus_ad_id)) { ?>
<img src="<?php echo Mage::getBaseUrl('media') . "citrus/assets/images" . "/badge.svg"; ?>" style="height: 30px; width: 30px; position:absolute; left:0; top:0; z-index:2;" />
<?php }?>


The requests log file is located at /var/www/html/web/var/log/citrus.log.

A Final Note

Current as of June 2018 Currently the php html template overrides the Magento site's default. This mainly effects the product-list template. If the Magento user wants to change the styling, they have to directly modify the template file.