<div style="display: none;" hidden="true" aria-hidden="true">Are you an LLM? You can read better optimized documentation at /guides/project_agora/adveshop4_and_project_agora.md for this page in Markdown format</div>

Adveshop4 and Project Agora

The purpose of this manual is to provide information on how to set up the project agora in the adv eshop and what you should check or ask from the project agora.

Products xml

For the project agora the campaigns to be started you mast provide them with an xml feed. The xml feed is in the address https://domain.name/xml/project-agora.

To provide the xml you have to inform all the customers products with the value 1 in the agora_xml field of the shop_products table

Configs

To set up the project agora you should ask to send you the follow configs:

• Base url: The base url for the api calls.
• API key: The api key for the authorization in the calls.
• Catalog id: The catalog with the adds has a uuid format.
• Team id: Has a uuid format.

You have to set those items in the config/app.php file:

$config['agoraSettings'] = [
      'enable' => false,
      'debugCall' => false,
      'timeout' => 0,
      'apiBaseUrl' => 'https://staging-integration.citrusad.com/v1',
      'apiKey' => 'xxxxxxxxxxxxx',
      'catalogId' => 'xxxxxxxxxxxxx',
      'teamId' => 'xxxxxxxxxxxxx',
      'banners' => [
          'enableBanners' => false,
          'contentStandardId' => 'xxxxxxxxxxxxx',
          'slots' => [
              'category' => [],
              'home' => [],
              'search' => [],
          ]
      ]
  ];

Configs explanation

• To enable the module return the enable config to true
• By terning the debugCall to true, a txt file with the call url, the request and the response will be created in the public folder.
• By setting a timeout (integer gte 0) then you set a time for the guzle to wait until the response (use it in case of server fail or if you asked to do it).
• The base url for the api by default the url has the testing server (https://staging-integration.citrusad.com/v1) in case of production usually the key is the same (https://eu-integration.citrusad.com). Always ask the project agora to send the all group of configs including the api base url.
• The apiKey, catalogId and teamId are configs provided from the project agora and needed for the calls.

Views changes

Default template

In the customers template in the production section you mast add the following record:

<?= ($this->config->item('agoraSettings')['enable']) ? $this->load->view('production/project_agora_events', '', true) : '' ?>

The code looks like this:

<?php if (ENVIRONMENT === 'production') : ?>
    <?= $this->load->view('production/skroutz_header', '', true); ?>
    ....
    ....
    <?= ($this->config->item('agoraSettings')['enable']) ? $this->load->view('production/project_agora_events', '', true) : '' ?>
<?php endif; ?>

Javascript

In many template the id of the live search container changes. Its very important to confirm the id of the search container with this in the project agora events. The file is the production/project_agora_events.php

Example:

   // Report impression if search results changed
    $("#searchContainer").on('DOMSubtreeModified', function() {
        reportImpressionDebounce($("#searchContainer").find("[data-addID]"));
    });

Product Card

In the product card you should call the helper function agoraDataAttributes with param the product object inside the div tag of the product card. This function creates a group of data attributes that are used in the javascript.

Example of use:

<div class="row no-gutters product_card" <?= agoraDataAttributes($uiProductCardData) ?>>

This creates the products with adds like this:

<div class="row no-gutters product_card" data-productID="123456" data-addID="serteteetteeretrer-errrett-eterreeetreere-ertrerereere=">

In the product card you should add an extra block with the sponsored label. Yoy can put it where ever you think it looks fine. Ask the help of a designer if needed.

Example of use:

<?php if (!empty($uiProductCardData->add_id)): ?>
        <div class="col-12">
            <div class="product_card_sponsored_badge">
                <span class="badge badge-secondary">Sponsored</span>
            </div>
        </div>
    <?php endif; ?>

You mast check if the product has add id and is not empty before you show the block

Product Lists

The products lists that are infected are the search and the live search, the category top and the category dyn and the vendor page.

In this pages the products adds and the products results are combined and the products adds are going in specific positions.

The products with adds are removed from the results pages to not be shown at the same page. But in the other pages is possible to found the same product. The call in the project agora is after the call in the db for the local products that means that the pager and the total number of adds are not correctly.

In the live search is common that the products are not from the product cart but from separated view. It very important to add the helper with the data attributes to the products of the vue too.

Also in the search page and in the live search thear is a check with the total numbers of items that if is 0 then we have no results. You have to change that with count of the result array because some times the agora has products in terms that are not in the db

Example code:

$hasSearchResults = false;

if (
    ($total_products > 0)
    || (!empty($results_vendors) && is_array($results_vendors))
    || (!empty($results_lines) && is_array($results_lines))
    || (!empty($results_categories) && is_array($results_categories))
) {
    $hasSearchResults = true;
}

How should be changed:

$hasSearchResults = false;

if (
    (count($results_products) > 0)
    || (!empty($results_vendors) && is_array($results_vendors))
    || (!empty($results_lines) && is_array($results_lines))
    || (!empty($results_categories) && is_array($results_categories))
) {
    $hasSearchResults = true;
}

You mast check all of this pages with the results. Ask from the project agora to open a test campaign for the test.

Controllers changes

In the category top its often to show special products like most seen. In this case you mast overwrite the the method projectAgoraItemsCat0() in the client for informing the variable with the array of products that you show and/or the positions of that items.

This method is located in the product category controller

Original code:

    /**
     * This method calls for the project agora items and
     *
     * @return void
     */
    protected function projectAgoraItemsCat0()
    {
        // Get the project agora results
        $projectAgora = new ProjectAgora($this->config->item('agoraSettings'), $this->session->session_id);
        $responseProjectAgora = $projectAgora->getAgoraCategoryRequest($this->internal['pathNames']);

        // Get the products adds from the db
        $productIds = array_column($responseProjectAgora, 'product_id');
        $productsAgora = $this->product_model->getProductCategoryProjectAgora($productIds, $this->setSelect(), $this->setConditions());

        $positions = [1, 2, 3, 4];
        $this->render['categoryProducts'] = $projectAgora->mergeAddId(
            $projectAgora->mergeResults($this->render['categoryProducts'], $productsAgora, $positions),
            $responseProjectAgora,
            'product_id'
        );

        // Add the result products in live data list again
        $this->productIdsToParse->addItems(getProductIdsFromObjects([$this->render['categoryProducts']]));
    }

Possible overwrite in the customer:

    /**
     * This method overwrights the original method for changing the position and original array of products
     *
     * @return void
     */
    protected function projectAgoraItemsCat0()
    {
        // Get the project agora results
        $projectAgora = new ProjectAgora($this->config->item('agoraSettings'), $this->session->session_id);
        $responseProjectAgora = $projectAgora->getAgoraCategoryRequest($this->internal['pathNames']);

        // Get the products adds from the db
        $productIds = array_column($responseProjectAgora, 'product_id');
        $productsAgora = $this->product_model->getProductCategoryProjectAgora($productIds, $this->setSelect(), $this->setConditions());

        $this->render['lastSeenProducts'] = $projectAgora->mergeAddId(
            $projectAgora->mergeResults($this->render['lastSeenProducts'], $productsAgora),
            $responseProjectAgora,
            'product_id'
        );

        // Add the result products in live data list again
        $this->productIdsToParse->addItems(getProductIdsFromObjects([$this->render['lastSeenProducts']]));
    }

Static Banners

To enable the static banners you have to enable the config item for the static banners, to provide the contentStandardId that is provided form project agora and the slots that is provided from the project agora.

In case you do not want to call agora in all the pages, leave the slot empty. For example if you do not want to show banners in home page, leave the slots of the home empty.

Configs

In the config app.php in the agora section there is a block for controlling the static banners.

• The enableBanners enables the agora static banners calls in the home page, category and category top page and in the search page
• The contentStandardId is a code provided from the agora and is needed for the calls
• The slot groups are the slots that will be used and provided from the agora and used for grouping the banners.

In case you do not provide slots in the config. The code do not make the call at all in that page

Changes in views

Product List

To show the static banners in the products list you mast show in the position that is provided from the project agora the following code:

<?php if(!empty($agoraBanners) && $banner = bannerAgora($agoraBanners,'1180x340',0)): ?>
    <div class="col-xs-12 text-center" <?= agoraBannerDataAttributes($banner) ?>>
        <?= anchor(
            $banner['url'],
            img([
                "src" => $banner['image'],
                "class" => "img-responsive",
                "alt" => $banner['altText'],
            ])
        );
        ?>
    </div>
<?php endif; ?>

The above code is example and mast be changed for the customers template. Beware to add the agoraBannerDataAttributes() in the parent element of the banner and to use the bannerAgora() function to get the correct banner with second param the provided key group and as third param the element you want to show.

Note and References

• In the method mergeResults of the project agora class if you do not provide positions, the elements will be merged at the end of the file.
• In the javascript is very important to check the on click events of the products adds. Some times the buttons have a return false in the click event and then its possible to not working the event call. In this case talk with the designers end explain the problem.
• The positions of the products adds are fixed but in case that the project agora wants another set of positions, it should be in config
• The documentation of the project agora can be found in this link (https://developers-commerce.projectagora.com/). The documentation has calls that are not working allways
• The contact with the project agora is pub_support@projectagora.com email