Manually Controlling Recommendations

Slot-based Inclusions and Exclusions

ATG Recommendations allows you to manually specify products which should be included in, and/or excluded from, the recommendations generated for a given slot. You may control which products are recommended with any combination of the following slot parameters:

• includeFirst – specifies a list of product ids for products which must be recommended and displayed first in the slot
• includeRandom – specifies a list of product ids for products which must be recommended and displayed randomly throughout the slot
• exclude – specifies a list of product ids for products which must not be recommended in the slot

Note: the product ids in the above parameters must match the product ids provided in the ATG Recommendations Catalog Feed.

If the number of recommendations requested is greater than the number of manually included products, the remainder of the slot will be populated with dynamically generated recommendations.

In the following example, we request five recommendations; we specify two products which must appear first in the slot, one product which must appear randomly in the slot, and one product that must not appear in the slot.

  <div id="cs-recslot" class="cs-slot">
    <dl class="cs-cfg" style="display:none">
      <dt>headerText</dt><dd>We Recommend</dd>
      <dt>numRecs</dt><dd>5</dd>
      <dt>includeFirst</dt><dd>
        <dl>
          <dt>exampleProductId1</dt>
          <dt>exampleProductId2</dt>
        </dl>
      </dd>
      <dt>includeRandom</dt><dd>
        <dl>
          <dt>exampleProductId3</dt>
        </dl>
      </dd>
      <dt>exclude</dt><dd>
        <dl>
          <dt>exampleProductId4</dt>
        </dl>
      </dd>
    </dl>
  </div>

An example response for this request may return recommendations in the order: exampleProductId1, exampleProductId2, exampleProductId7, exampleProductId3, exampleProductId5. Notice that the two products indicated in the includeFirst parameter appear first (and in the order they were listed), the product indicated in the includeRandom parameter appears fourth (though it could have appeared in any position after the products specified by includeFirst). The remaining products were dynamically generated, and do not include the product specified in the exclude parameter.

Catalog-based Inclusions and Exclusions

ATG Recommendations also allows you to manually specify products that should be included in, and/or excluded from, the recommendations for a given product when viewing its detail page. A page is considered to be a product detail page when the cs-cfg <div block includes a productId value. You may control which products are recommended with any combination of the following product catalog elements:

• <g:includeFirstRecs>p1,p2,p3</g:includeFirstRecs> – specifies a list of product ids for products which must be recommended and displayed first in each slot in the page.
• <g:includeRandomRecs>p4,p5,p6</g:includeRandomRecs> – specifies a list of product ids for products which must be recommended and displaued randomly through each slot in the page.
• <g:excludeRecs>p7,p8,p9</g:excludeRecs> – specifies a list of product ids for products which must not be recommended in any slot.

As with slot-based inclusions, if the number of recommendations requested is greater than the number of manually included products, the remainder of the slot will be populated with dynamically generated recommendations.

Please contact ATG Recommendations Client Services to enable catalog-based inclusions and exclusions for your site.

Rules and Precedence

Slot-based inclusions and exclusions and catalog-based inclusions and exclusions can be used at the same time. In effect, the catalog-based inclusions and exclusions are appended to the slot-based inclusions and exclusions when a slot is rendered.

Products specified in either the includeFirst or includeRandom parameters will be recommended regardless of the state of the recommend, instock or expiration_date catalog fields, or any campaigns active on the slot . For example, if you mark a product as out of stock in the catalog, we will typically not recommend this product; however, if the out-of-stock product is specified in one of the include parameters, it will be recommended. A product specified in an include parameter will be recommended as long as the product exists in the catalog and has values for name, productId, productUrl, and imageUrl.

In correlation with the above, include parameters take precedence over exclude parameters. That is, if the same product is indicated in both an include parameter and in the exclude parameter, that product will be recommended.

Finally, if a product is indicated in both the includeFirst and includeRandom parameters, includeFirst will take precedence.

For example, if a product in your catalog has the definition

  <item>
    <title>Blue Jeans</title>
    <description>A rugged pair of pants</description>
    <link>http://mystore.com/clothes/mens/pants/bluejeans.html</link>
    <g:id>43920</g:id>
    <g:image_link>http://mystore.com/images/bluejeans.jpg</g:image_link>
    <g:price>$50.00</g:price>
    <g:includeFirstRecs>11111,22222</g:includeFirstRecs>
    <g:includeRandomRecs>33333</g:includeRandomRecs>
    <g:excludeRecs>55555,66666</g:excludeRecs>
  </item>

and the user visits a page that contains the configuration div

  <div id="cs-cfg" style="display: none">
    <dl class="cs-cfg">
      <dt>retailerId</dt><dd>Your Retailer Id</dd>
      <dt>view</dt><dd>
        <dl>
          <dt>productId</dt><dd>43920</dd>
        </dl>
      </dd>
    </dl>
  </div>

and a recommendation slot with

  <div id="cs-recslot" class="cs-slot">
    <dl class="cs-cfg" style="display: none">
      <dt>headerText</dt><dd>Recommendations for you:</dd>
      <dt>numRecs</dt><dd>6</dd>
      <dt>includeFirst<dt><dd>
        <dl><dt>77777</dt></dl>
      </dd>
      <dt>includeRandom<dt><dd>
        <dl><dt>88888</dt></dl>
      </dd>
      <dt>exclude<dt><dd>
        <dl><dt>99999</dt></dl>
      </dd>
    </dl>
  </div>

The first three recommendations will be 77777, 11111, and 22222, in that order. Of the remaining three recommendations, one will be 33333, one will be 88888, and one will be dynamically generated by ATG Recommendations, but will not be 55555, 66666, or 99999.