Step 1 - Register an account

If you don’t already have a TruRating account for your online store, please go to www.trurating.com/registration to get your account up and running!
If you’d like to activate additional outlets, please contact us

Step 2 - Insert JavaScript snippet

Add TruRating Online JavaScript to your Payment Confirmation Page and set the parameter values.

<script>
  var TRURATING =
  {
      "transactionId" : "Transaction identifier",
      "transactionDateTime" : "Transaction time (UTC)",
      "isTransactionSuccess" : true,
      "isLive" : true,
      "languageCode" : "2 letter ISO 639-1 language code",
      "countryCode" : "2 letter ISO 3166-2 country code",
      "customerId" : "Non personally identifiable user specific identifier",
      "currency" : "ISO 4217 numeric currency code",
      "transactionAmount" : 0,
      "shoppingBasket" : {
        "items" : [
              {
                "skuCode": "SKU Code",
                "unitAmount": 0,
                "description": "Product description",
                "retailAmount": 0,
                "sellingAmount": 0,
                "categories": ["Category1","Category2"],
                "department": "Department"
              }
          ],
          "discountCodes": ["Code1", "Code2"],
          "deliveryCharge": 0,
          "deliveryMechanism": "Delivery mechanism",
          "subTotalAmount": 0
    },
    "utmParameters" : {
      "utmSource": "UTM source",
      "utmMedium": "UTM medium",
      "utmCampaign": "UTM campaign",
      "utmTerm": "UTM term",
      "utmContent": "UTM content"
    }    
  };
  (function() {
  TRURATING.ver = "3.0.2"; TRURATING.t1 =new Date().getTime(); 
  var tr = document.createElement("script");
  tr.id = "tr-ecomm-widget-src"; tr.type = "text/javascript";
  tr.async = true; tr.src = "https://ecommwidget.trurating.com/js?ver="+TRURATING.ver;
  var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(tr, s);
  })();
</script>

The tables below provide an overview of the data collected and some guideance on usage. All elements are required where available.

Parameter Description Data Format
transactionId Transaction identifier. This is a merchant specific unique identifier for the transaction. string (max length: 100 characters)
transactionDateTime Transaction Time in UTC Format. Timestamp should always be represented as UTC time. string
ISO 8601 yyyy-MM-ddTHH:mm:ssZ format is expected.
e.g. 2016-07-01T10:15:30Z
isTransactionSuccess true if the transaction was successful, false otherwise. If the transaction has failed, TruRating Online will not be displayed boolean
isLive boolean value indicating whether the TruRating Online widget is in ‘Live’ or ‘Test’ mode . false is to be used when a merchant is testing the integration. Ratings captured while in ‘Test’ mode will not be shown on the TruRating analytics dashboard Important:
Merchants must make sure this is set to true prior to capturing live ratings
boolean
languageCode 2 letter ISO 639-1 language code (e.g. 'en' for English) in which the question to be displayed. Refer Language Codes for more information string (max length: 2 characters)
e.g. en for English
countryCode 2 letter ISO 3166-2 country code (e.g. "au", "uk", "nz", or "us"). If this is present, TruRating will attempt to display a question localised to the specified country.
Refer Country Codes for more information
string (max length: 2 characters)
customerId SHA256 hash (Hexadecimal encoded) of customer email address. string (max length: 100 characters)
currency ISO 4217 numeric currency code (AU (36), NZ (554), UK Pound (826), USD (840), USN (997). Refer Currency Codes number
e.g. 826 for Pounds Sterling
transactionAmount Total value of the transaction expressed in the minor currency unit. e.g. USD 12.34 should be represented as 1234 number
shoppingBasket.items An array containing an item corresponding to each item in shopping basket - supplied when available array
shoppingBasket.items[n].skuCode SKU code. Please note that [n] is used to refer to individual items within the shoppingBasket.items array array of string (max length of each item in array - 100 characters)
shoppingBasket.items[n].unitAmount Selling Amount x Quantity number
shoppingBasket.items[n].description Short description of the item string (max length: 100 characters)
shoppingBasket.items[n].retailAmount Retail amount for a single item prior to any discounts and excluding tax, expressed in the minor currency unit number
shoppingBasket.items[n].sellingAmount Selling amount for a single item after discounts have been applied, expressed in the minor currency unit number
shoppingBasket.items[n].categories Product categories array of string (max length of each item in array - 100 characters)
shoppingBasket.items[n].department Department (if applicable) string (max length: 100 characters)
shoppingBasket.discountCodes Discount code(s) used array of string (max length of each item in array - 100 characters)
shoppingBasket.deliveryCharge Delivery charge expressed in the minor currency unit number
shoppingBasket.deliveryMechanism Delivery mechanism string (max length: 100 characters)
shoppingBasket.subTotalAmount Final subtotal adjusted amount for this basket excluding tax expressed as the minor currency unit number
utmSource utm_source which identifies a search engine, newsletter name, or other source. Example: google string (max length: 100 characters)
utmMedium utm_medium which identifies a medium such as email or cost per click. Example: cpc string (max length: 100 characters)
utmCampaign utm_campaign which identifies a specific product promotion or strategic campaign string (max length: 100 characters)
utmTerm utm_term value. Identifies search terms string (max length: 100 characters)
utmContent utm_content value. Identifies what specifically was clicked to bring the user to the site, such as a banner ad or a text link. string (max length: 100 characters)

Key Implementation Points

From previous implementations we have seen the following issues commonly occur:

  1. Time stamp is not correct. It should be: ISO 8601 yyyy-MM-ddTHH:mm:ssZ format is expected (e.g. 2016-07-01T10:15:30Z)
  2. All amounts should come in as minor unit of currency (i.e. $14.67 is sent as 1467)
  3. CustomerId should be a SHA256 hash of the customer email address
  4. isLive should only be set to true once testing is complete (if it is set to false data will not be loaded into the dashboard)
  5. Merchant website base styles being set as !important could cause some of the TruRating Online styles to be overwritten, therefore distorting the display of the widget

Language Codes

Listed below are the language codes currently supported by TruRating Online. This will be updated as support for more languages are added.

Language ISO 639-1 Language Code
English en

Country Codes

Few sample country codes are listed below. Please refer ISO 3166-2 Country Codes for a full list of country codes

Country ISO 3166-2 Country Code
Australia au
Canada ca
New Zealand nz
United Kingdom gb
United States of America us

Currency Codes

Currency codes are represented as ISO 4217 numeric codes.

Few sample currency codes are listed below. Please refer ISO 4217 Currency Codes for a full list of currency codes

Currency ISO 4217 Numeric Code
Australian Dollar 36
Canadian Dollar 124
Euro 978
New Zealand 554
Pound Sterling 826
United States Dollar 840

Sample SKU Data

Here is an example of what the SKU data is to look like:

"shoppingBasket": {
    "items": [
      {
        "skuCode": "10011717-7",
        "unitAmount": 1,
        "description": "Black Cherry Heritage Canvas Men's Classics",
        "retailAmount": 7995,
        "sellingAmount": 7995
      },
      {
        "skuCode": "10011704-7",
        "unitAmount": 1,
        "description": "Majolica Blue Heritage Canvas Men's Classics",
        "retailAmount": 7995,
        "sellingAmount": 7995
      },
      {
        "skuCode": "10011669-5",
        "unitAmount": 1,
        "description": "Antique White Heritage Canvas Women's Classics",
        "retailAmount": 7995,
        "sellingAmount": 7995
      }
    ],
    "discountCodes": [
      "WELCOME15"
    ],
    "deliveryCharge": 0,
    "deliveryMechanism": "Delivery mechanism",
    "subTotalAmount": 20388
  },

Step 4 - Carry out integration validation checks

Following completion of the technical integration phase, the merchant (or the party responsible for implementing the integration) should carry out integration validation checks to ensure that the merchant’s web site, TruRating Online and any other integrations that may be present continue to function as expected when deployed on the same page. These checks should be performed immediately prior to switching to live.

Listed below are some of the high-level checks that need to be carried out on both desktop and mobile browsers.

  • Merchant web site functionality should not be changed/affected following the integration
  • Merchant web site visual appearance should not be changed/affected following the integration
  • TruRating Online should be displayed typically within about 5 seconds of loading the Payment Confirmation Page. This could vary based on the quality of user’s internet connectivity though.
  • Users should be able to complete TruRating Online user journey successfully
    The user journey consists of:
    • Seeing a question
    • Being able to rate
    • Seeing an acknowledgement for rating
    • (Optionally) Providing additional feedback as a comment. Note: if no comment is added then TruRating Online will close/hide automatically in about 30 seconds
Feedback