ATG Recommendations Quick Start Guide

How to Install and Display ATG Recommendations

ATG Recommendations are easy to install. Once you receive your Retailer ID, just add a few lines of HTML to your product pages, cart, style sheet, and put a <DIV> where you want to display your recommendations!

Step 1: Request a Retailer ID

Step 2: Make Your Product Catalog Available to ATG Recommendations

Step 3: The ATG Recommendations JavaScript Include

Add this <SCRIPT> to the <HEAD> element on every page where the tracking code (step 4) is implemented. For more options please see flavors.

<script type="text/javascript" charset="utf-8" src="//static.atgsvcs.com/js/atgsvcs.js"></script>

Step 4: Clickstream Tracking Code

Add this <DIV> to the <BODY> element of every product detail page. Replace the placeholder text appropriately. For instructions on non-product pages please see the section entitled Handling Non-Product Pages .

  <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>Your Product Id</dd>
        </dl>
      </dd>
    </dl>
  </div>

Using Customer Ids to Recognize Visitors Across Channels and Browsers

ATG Recommendations uses persistent cookies to recognize return visitors from one session to another. Since cookies are stored by the visitor’s web browser, they only allow recognition of a return visitor when that visitor uses the same computer and web browser in each session.

If your web site assigns persistent ids to your customers, ATG Recommendations can use those ids to recognize your customers even when they visit your site using different computers in different sessions. Persistent customer ids also allow ATG Recommendations to use a customer’s online activity to personalize recommendations delivered through other channels like email and call center applications, and they allow ATG Recommendations to recognize return customers even if they delete their browser cookies.

To include customer ids in your web pages, add them to the clickstream tracking code as shown here. Remember to replace the placeholder text with the appropriate values.

  <div id="cs-cfg" style="display: none">
    <dl class="cs-cfg">
      <dt>retailerId</dt><dd>Your Retailer Id</dd>
      <dt>customerId</dt><dd>Your Customer Id for the Current Customer</dd>
      <dt>view</dt><dd>
        <dl>
          <dt>productId</dt><dd>Your Product Id</dd>
        </dl>
      </dd>
    </dl>
  </div>

To include customer ids in your email templates when using ATG Recommendations for email, refer to the Email Recommendations User Guide, available from your client services account manager or by emailing ATG Recommendations Support.

The id that you provide may be a customer number that you store as part of your customer profile. You may also provide some other type of customer id if you have an appropriate value available. What is important is that the value you choose uniquely identifies a customer, that it does not change from session to session, and that the same id is available in all channels where you want to deliver recommendations.

You should only include the customer id once you have positively identified the customer. You should not provide transient customer ids or ids that are only valid during a single web session. If your site does not allow users to log in or does not maintain consistent customer ids for each customer, you should not provide customer ids in your clickstream tracking code at all.

To preserve the privacy and anonymity of your customers you should avoid using a customer’s real name, email address, telephone number, social security number, login name, or any other information that could potentially constitute personally identifiable information (PII) as the customer id.

You can provide the customer id at any point during the web session. For example, if a customer comes to your web site, browses around for a while, and then logs in to make a purchase, you can provide the customer id at any point after the login. You only need to provide the customer id once per web session, but there is no harm in providing it on every page view once you have identified the customer.

If your web site is built on ATG Commerce we suggest using the customer’s profile id, available in the page as Profile.repositoryId, as the customer id. You should check the Profile.transient property to see whether the customer has logged in before including the profile id in your page tags. If your ATG-powered site supports auto-login through cookies or URL parameters, you may also want to check Profile.securityStatus to determine the method by which the customer was authenticated and include the customer id only if the customer logged in with a user name and password.

Step 5: Cart Checkout Tracking

Checkout tracking gives ATG’s Recommendation Engine a final snapshot of your customer’s buying session. This information is key to maximizing recommendation accuracy. Cart checkout integration should be implemented only when an order is being submitted for processing, such as on an order receipt page. Cart checkout does not track cart changes and should not be placed on a cart display page.

Don’t forget to include the ATG Recommendations JavaScript from Step 3 on your cart pages.

Cart data is extracted directly from an html microformat (described below). This requires that your cart system generate an additional chunk of hidden html.

Add this <DIV> element to your cart template page. Then replace the pseudocode and the placeholder text.

  <div id="cs-cfg" style="display: none">
    <dl class="cs-cfg">
      <dt>retailerId</dt><dd>Your Retailer Id</dd>
      <dt>-checkout</dt><dd>
        <dl>
          <dt>activation</dt><dd>now</dd>
          <dt>cart</dt><dd>
            <dl>
              <dt>productIds</dt><dd>
                <dl>
                  foreach (line item in the cart) {
                  <dt>Your Product Id</dt>
                  } // foreach
                </dl>
              </dd>
              <dt>totalPrice</dt><dd>Total Price of the Cart</dd>
            </dl>
          </dd>
        </dl>
      </dd>
    </dl>
  </div>

If you are using customer ids to recognize visitors across channels or browsers remember to include the customer id in your clickstream tracking code just as you did for product detail pages. The first few lines of your cart checkout tracking code should look like this:

  <div id="cs-cfg" style="display: none">
    <dl class="cs-cfg">
      <dt>retailerId</dt><dd>Your Retailer Id</dd>
      <dt>customerId</dt><dd>Your Customer Id for the Current Customer</dd>
      <dt>-checkout</dt><dd>
      ...

Example:

  <div id="cs-cfg" style="display: none">
    <dl class="cs-cfg">
      <dt>retailerId</dt><dd>decafbad</dd>
      <dt>-checkout</dt><dd>
        <dl>
          <dt>activation</dt><dd>now</dd>
          <dt>cart</dt><dd>
            <dl>
              <dt>productIds</dt><dd>
                <dl>
                  <dt>beaded</dt>
                  <dt>bedded</dt>
                  <dt>bedead</dt>
                  <dt>bedeaf</dt>
                </dl>
              </dd>
              <dt>totalPrice</dt><dd>300.00</dd>
            </dl>
          </dd>
        </dl>
      </dd>
    </dl>
  </div>

Step 6: Container `<DIV>` Element for Recommendations

Add this <DIV> element to the page where you want recommendations displayed. Replace the placeholder text appropriately.

  <div id="cs-recslot" class="cs-slot">
    <dl class="cs-cfg" style="display: none">
      <dt>headerText</dt><dd>Text to Display Above Recommendations (optional)</dd>
      <dt>numRecs</dt><dd>Number of Recommendations to Display</dd>
    </dl>
  </div>

Step 7: CSS to Style the Appearance of Recommendations

This CSS may be embedded directly into the page or appended to your existing stylesheet. (More on styling in Step 9)

  #cs-recslot {text-align:left; padding:0; font:12px Arial, sans-serif;}
  #cs-recslot .cs-header-text {font: bold 17px Arial, sans-serif; color:#000;}
  #cs-recslot .cs-rec {float:left; width:125px; text-align:center; padding:3px; margin:10px;}
  #cs-recslot img {width:100px; padding:3px; border:0;}
  #cs-recslot a {color:#000; text-decoration:none; margin:5px;}
  #cs-recslot a:hover {color:#999;}
  #cs-recslot a span {display:block; clear:both;}
  #cs-recslot .cs-price {margin:0; padding:0; padding-top:3px; font-weight:bold;}
  #cs-recslot a:hover .cs-price {color: #000;}

Step 8: Testing Your Site

ATG Recommendations uses the information collected by clickstream tracking to understand and predict the behavior of visitors to your web site and to improve the accuracy of recommendations. When you are developing and testing your web site you will want ATG Recommendations to ignore the data from your test sessions so that testing doesn’t influence the recommendations that are ultimately delivered to your shoppers.

To tell ATG Recommendations that a web session is part your development and testing activity rather than a real shopping session, add the debugOn flag to your clickstream tracking code so that the first few lines of your tracking code look like this:

  <div id="cs-cfg" style="display: none">
    <dl class="cs-cfg">
      <dt>retailerId</dt><dd>Your Retailer Id</dd>
      <dt>debugOn</dt><dd>true</dd>
      ...

You should add the debugOn flag to the clickstream tracking code for all pages including product, cart, checkout, and non-product pages. The debugOn flag must appear in the first request of the session for ATG Recommendations to consider it a development and testing session. This is especially important if you are load testing your site, since the number of simulated site visits generated during load testing may be enough to affect recommendations.

Don’t forget to remove the debugOn flag from your clickstream tracking code when you have finished testing and are ready to go live with ATG Recommendations.

Step 9: Enhancing Your Implementation

Documentation
Quick Start Guide
Catalog Format
Renderers
Flavors
Optimizing Revenue
Handling non-Product Pages
Manual Recommendations
Multiple Recommendations
Fail Over
License & OSS Attributions

Tools
ATG Recommendations Helper Plugin

Have questions?