HomeGuidesChangelog
Log In
Guides

Universal beacons

This page breaks down the universal beacon feature and explains how to transition from standard beacons

📘

Universal beacons offer a streamlined and efficient way to manage ad tracking by simplifying the beacon structure and reducing the number of requests sent.

Below, we present a breakdown of how universal beacons work and how to migrate to this setup.


Key features of universal beacons

  1. Minimized response:

    • Product-level onLoadBeacons are removed, leaving just a single onLoadBeacon at the placement level. This simplifies the overall tracking process.
  2. Reduced requests:

    • By having a single OnLoadBeacon per placement, the total number of beacon requests is minimized, leading to less network traffic and improved performance.
  3. Feedback mechanism:

    • Universal beacons include a feedback mechanism to report on why certain products were not rendered.
    • This allows for detailed reporting and better optimization of the overall fill rate - leading to more revenue.

⚠️

Trigger other beacons normally

While the universal beacon simplifies the tracking process, it’s important to remember that other product-level beacons (such as OnView, OnClick, OnBasketChange, and OnWishlist) still need to be triggered as normal. These beacons ensure that specific interactions with individual product tiles are accurately tracked and reported.


Migrating from standard to universal beacons

📘

To migrate to universal beacons, you need to coordinate with your Technical Account Manager (TAM).

Here’s how you can make the transition:

  1. Enable the forceuniversal parameter in pre-production
    Add the parameter &forceuniversal=1 to all API calls in your pre-production environment.

  2. QA
    Collaborate with your TAM to test the new beacon logic in the pre-production environment to ensure it functions correctly.

  3. Deploy to production
    Once the QA phase is successful, release the new logic into the production environment with the &forceuniversal=1 parameter included in all API calls.

  4. Internal update
    Criteo will update your internal configuration to automatically send universal beacons in your ad responses, eliminating the need for the &forceuniversal=1 parameter.

  5. Parameter removal
    You can then remove the &forceuniversal=1 parameter from your API calls at your convenience.


Using universal beacons

API call example

Here's an API call example using curl.

Notice the forceuniversal=1 parameter:

curl -X GET "https://d.us.criteo.com/delivery/retailmedia?criteo-partner-id=108341&retailer-visitor-id=456&customer-id=789&page-id=viewHome_API_desktop&event-type=viewHome&verbosity=min&forceuniversal=1" \
-H "Referer: https://www.criteo.com" \
-H "X-Forwarded-For: 123.456.789.012" \
-H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"

API response example

{
  "status": "OK",
  "placements": [
    {
      "viewCategory_API_desktop-InGrid": [
        {
          "format": "sponsored_products",
          "products": [
            {
              "ProductId": "18980",
              "ParentSKU": "18980",
              "OnLoadBeacon": "",
              "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=N-ShKii9k_Ssq07X2u05ueDtr86KFpQ_fGxGemRVh6ynpV--gKQpqQ5FXWm2jih5WL-bJVGa3yAsWPQVjU2j5fMqwDUfn1fdsUIoSDT5aKRthW6ML3ccNRI7cI2keo4TJgYLwuz51QkBM3s7Gf4hg0es63qyxhLUeWUwEF_rqySkHbAZPRg5wvmgzp8wzv7R-m4660kCeescoV-uFJDx_GzYou_DTSF6_UGzyx__SGbxr9eqRigYDK5mFvmfJsYIZrcmIjLjWRFzoD4ugdSv5JpubyCKzl-GBXVaP6Hfr7CkM4rG7p7LdJw5lFzMqARAt1INGfz5ZPcjuS2bDAvxdGsiJPtTAlXnTkUQs3wtKStMerGH5fCT27l38O5QVY5u4L2OPtiQpk3OqSK8Q3RTLixQDeLXlJpD8-Z96hZYYmUFI-O0TcfLNaaZr-0In_ewBqFK13lJ-CnXDlhTh7f6eg&ev=4",
              "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=A1-el1RLyd3kFjXa3kxK-mDkA47htch79hUhLlQaPmUSgbOXU6lLZ0DHwMY1Hl4_obWgi1d2vI5egrxczuXkfLngIppGvApAysqR8j6Dh_woNs2GQus0Ktazq10P_j0Lh1Ea24r7x3GQpobN_DU5j1yWZKT27-qC1MY6FlbUuz6FsGLmsx-1pqVWoMGaDmRpMw9RyaVeuRTGyYS162s74rVAFrUzucXTrnpZjNkteFFa_oqCTpd1YAh2dNnblhUsMHbrQ0qWd6JfF4Ojz5sZa5OsjZCEMDnwOxU-aCSpzvjvVmSdgt3EMuVY_P-KCP66v_Ug9_L8EIaUe8Bep-_o7fuHhPlFb7PeXFBC7mQLjXBZOATK8u0LzK9aqK6hpSXgWnwOnVWjeRlCX7r6la3Z1kZF5Es52ZE2cnZYtII6aZoQxiK4jzCZ6fooBtolurDqmS-RbUMLqxC304rmuueUhHOS4f7rlcr2oU_rnqaxhRw&ev=4",
              "OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=G6d-bdVBQpa5bEP11vwqrODaP4mhmyTo-2uemQywvvI6JZF83Goi6-hMhjduPGEVaqceFsVZK8fPyHmXNx9ocWPBZHbWoFNldhYyac22vfs_5FJ0NhjHLq78ZcV2x6fTc5fZgQ73gMWGz6cpRFkZHMlB2IQLD3e-Td-Ho3YP3fUNNKQzM-yHc4RUcKsjZyQoncKScCDYr7jQe5OmPwl03gCu1XdUDMbz5-OB9APu-V8Y4lGza8rEF9Me--77mPi2NF0raPy-aI0mccj_tlJQtmJedxNGzPmf_kDDukbxYoU9sTT9SKOWEjdErAFQ2UVumUCoBv7s_BYjw8G2aNcU0mREFzTZwj9hq5vXb5ln4-0q-5sIuc-rb1MdaJjvIsF3Ci4omovDooeZ6Xqadoh0Q_Oc8gHlJNH9o2WXDXXxjskKjUQEvNC1c_TbI5s5xcNtyrG7WX80Dc3pVO9_Sd2hThATt2gLVHijo36dXFdMa-8&ev=4",
              "OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=llE74E1HyOfUwQrToJb5mqlLadGyJnAK5HdkKyVKtWfEP3chiF9GFpgmecYRXOvQMSgXYkuTlmJ_CkjdH4nVDqPxwZbFsT8wMy5kFa7hEDjlrRN65xmQQqvuLw-BQRd53WPXUp2d8UaMBVHT6Km5ANS5iFGHQwtMkjlU5PoIpLnDWZOmaf2nH3Xu5ZIwa3nINGkENMF31_70elrw29z21ZoLcOY1AF2Gk7IkYU-SgB3AqPTwuIKKqpB8eHcvL3vCCzNElLi5tOVORBzYJall-YPHOpv1mdxo1aKQhPMthEez5uSGvA-TGEs0gTuF5KRPSAt1ZKO5oh920pdAY_05vQNGq3IpKWnoK-68OjeiISw8eX2EJlXeaIX2-TzMQx3yVK1NT3fngVwiBFTDzKjtMhfiUA8vyQI19HiEU8LjWyEUIuW_H4PvbzBvxJQzPYyjuNdtZD8CrmAOaU13tdQtRezHbr_khkWCWXdhrsF_BzE&ev=4"
            },
            {
              "ProductId": "17942",
              "ParentSKU": "17942",
              "OnLoadBeacon": "",
              "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=fLTthwnThahZxZmquoRxO-4LQQQcFn6KKTt17T3aiS7iUbli5dwRpCcpaeY773cvWSkPywYkzUdnbQLSpiSMtmJtA9-UByhDcxIiVGprTEVXecfxibQ2t8tha_mD82PaP7bcWtEGhTIPB_7Sh4uMbRDsJvZXFkNDmeBUtYjYH1OayWORT19m1bK9xs7NOmhq8XWTYpV0eoySr197uJXr_tC1tTJsLpw9B1gdLJWE5eWYfvFyiALBOZb2SIzZW4Ebpj89NWCTQG1YWkBXZaLzeVWPTIG1T6xmPsm5ohEqZ1I7kMWrKlAc9pMIKLtm0QGTKPJG1JFuScRv79SF7fVIGCPMmD_HKWhoaVmOfhmvlKChqZIUaobEg-tnpRVlwJAjMv1vs4yQyfjdBPm9TWt353fZtgZC4O25iNEZVLodencliMRmN-bD1MqObqYBvV2ZU-94PxCF84kwSncvMLw4Kg&ev=4",
              "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=lI3GHpBoheOYxgnBViG67fpkTrw8kGQ7hm1tqpEI0GfPoq0ZXAaRa99aJTvj_wYLcl7-Ry8NuO5PMFiQXKFznTc6TeTTJ8SSHH_N7Je8CedTwns9XEoho5-LfcWaj3M2Zk1sC3G0a6R60QJJERbCp31okNm2g8818uOCqS7BV1cf75UgrumTVSQfUQhhnBQ6ESRGBFAcF5f5ZvNOaBnuZ0EtucRL8hbXAeD7kwjDK1ApsP0i3v9ypLC0QVHtLvs7MSCRr_g34wsv3agyKwvBHzOd7RICfF_D9tvuKQPb4h7PyunhUxxItZN14uXoEmWQV-ynFNqgCY9p5awKMAzsoW-b0DEsvj7iecSW0FyTwaAZwSbIq-Nt3YCVgNnAdYf8xX_4LsSH6jSJlpU6iloE7B1IkjQX3Gtg5-5HtzJaKjir1Aw9JFotkASjJtARNbLTSkN3J4tsrTzLRC6UeyTmPXo23E0ZoNW9F8ZFi8fNMho&ev=4",
              "OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=v79SCFQ5rlZ06qfqbHTvHRI56ohUDws-T9P5N9apIOgcRdkrBziCUKcHiq5KkeOEuL-RQCLyHc-xAlzBraVbqAXbs7c46JlrafCN_15KruMeYcPR8bCje3K03ZUn5cv-lsAZ9_H4dWIMPyWUNgydktwDU25azhp-cjnZpuyI6ujH570_pG8EbDJ5SR6aqwDSN5yIvJABECIFVLjdoRP8_ytn2uOpvWScwIvxZ0au2lI99SZrnmIRGvZHjQ9FFCnhPbEwbK31faEddmznNhgUyYF8EaPf0-_-fYtnHr9UlY3sBkc48HPtMayh4HYI46AlXUvo0o-cNLmasf9MkdTL2ijVX1oAK52awmixwj9vaBk2OKnNWJZWB6091KlAZURFeMqIPOycFFGlJeIeKNEQfjyI751COVd58zhJn7GYs-3eeQ0457ZG2C1dbdYDKCtyEcDvSQCPk0kpwIDIct1iDz7ZHEz9O8a1u8pYrZPe8WY&ev=4",
              "OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=Ax9-lQKiaVUcRjjo7M3cDjg_VrBsdnBp1bK7wjsbOK7K_rsibtceyPvPzjnEue7xan_ATFRNWKy8flZBD2m21LSTMHVJblmpC5IfnTdDXe8ZmJvwTSMfLvenm_ujIBX8xCWJQcaqVsKsdEEfrVizfWstwVTsOZQX1UAVd2HEYen4MOPuSE0G11GQrosJo-tzxmepOCZGiBpGUZAucoXXDZ_ZDqEm2ViZYLuK_962PqHLdJXSkXEDk4y_aQlefQ-FGPD916VqgWr9ei-l6I79ncLg7syeJvaDcN6cQT7qL3bc7Bfk3EWtt6aaavMBEm7oUHegZzA6_VLN602sxxoKvDoZWyclgFTPCaFjd7hPES0Z6NpFHT1hE57yfeTAJ_3-KkO55dJmnO_3XfnGqwZ0cBWAuTqyingLmvChHipXll1LqosFX0m8mLu4VZWqlNE9yWysFUb66vQbP0m7t9c5Iop6Potp32jgNshJYTxSvec&ev=4"
            }
          ],
          "rendering": "",
          "OnLoadBeacon": "//b.us5.us.criteo.com/rm?fid=1205&hl_qs_cmp=UuI4LMFkkrnpRE7z0TTT2aB3hglrxPB48XVDytIQlDZQLu7zkeGnv5Pm8-9K52-rZMkBTkaJIN38mgFfgl76hS3XO696Yui-e2tHR5cWRRsT1iXNoTTyFlJJLK6NDdOH2ePUCKu6gSfHVCFHrK6Ba2LAFqCeheNd7y40wNl-gDIsEE59q_YqQUxaFIxJOSWC6Lyj9fybBf4HWGuxS3bEuSuV4TXXkZQCiAi8suL3-Qo55_JVtrASEvhNxlw0JxlCYrx_thqBP-5x17jUH_NXKlUQeqGoDGaXRqSPKlM19u3dE8rd0M3Ba7BoPY-MjCegdw5kCmVRijvrH3531RPfvaEcIeEPsrOzNMwCA_l2chvHj-IheszCtRQdxWJ7sRyOLzf3y1nO3KrWMywSJJpcHx-Vf-AJc9S_g3Nk_UdkD8aE8PWnIgN8dlkJwo9Av-4JV0FnlwWNwAn2Ygi8xUIakcAYNlam4lsdamE-ewgLPQbjByEagJyeFQtjSg_h3YFAd9njdtkziKNrtmYaigCVpKbzTp34NWWN_Zap-nKsC1lQY2_LlZkpMq0Qq0npF7xc&ev=4&criteopartnerid=108341&nolog=1&action=universal&origc=A&pid=0c3bf1f4-0c32-4efd-8373-1a2c86e08c8d&rn=1455740606&u=1&rm_e=pgzSPvrz-PTX8wOho1D1Q7_zwuTI_ReutLMUwY4-l47Mg_FiEPUZ_Cr_W4tzu7wm3s5zBFHpufuvfUJoPhiipBZPSsbFuLRGG29IjBQ8X8KGdGXPvJAsLK3r8LcmIKibowD8NG90b7BvoRq0LAAo7q0lYUKnAaE7npmoUaT-VWE6_VKwDqMmQn5KLdyxnnmUs4IB5AQpHrdniJyojUYXFVzDillJ0LlCEo1Xxls6aWBYojCMAuJCtfrcnTMcXRwjTy9pCwZa5TqGCZfEz1asOjQ19zodBr5kylGDDkg9zrgUSHVwy62nIryQl2CbU-4PyTqRcmdz9OR8KLkPrW6Y5Kfwqm7LblMB8eHX-swUb8i_IJf-iFZPZlQFvI9gU5oe",
          "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=nWCQ1D0YYYhNJ8RFe0gsAZTX1U0Hj8qndrHlfVeZe4BbiY1IQAoQI0xfYPOGW1DT9KUN2gqqO_9jIXgOG0k1y7vn835cr7HP59D0jWg6_ZkgmUUehUA0ejDIGIXSps-Bi5wBnXv7BCKyk8_Soi3Lze4_qg1cwE3wq-2w5VPbeI64peSegx-l-RGNDRdCMTYxk3pl459LIHV4gQtd2jSf5SZQSkFfEPnhZTJjAdd5U0wF7JRDgAUC79-cobFO4IgJJMmB8PlG9iQzYJHHWZ9erWhHqG5O3ISpk3yermUywv4OTwxcKWTCJY3skBtdOxZo2BH9B0wYW3abEGNXNPBlLCnyHdDcEGCYeXRk1gWy5BnqtFY7xK8kVP_5-v_6OqankRl5JCDI__Z2JEmB-Nrq_Q&ev=4",
          "OnClickBeacon": ""
        }
      ]
    }
  ],
  "page-uid": "b24d9dea-aa9e-4c3c-a203-9d7f72c3db1c"
}

Notes on the response

  • OnLoadBeacons at the product level are empty:
    • Notice that the OnLoadBeacon for each product is empty. This is expected as there is only one OnLoadBeacon at the placement level when leveraging universal beacons.
  • Single OnLoadBeacon per placement
    • The OnLoadBeacon at the placement level contains all the necessary information, significantly reducing the number of beacons sent.
  • Action parameter
    • The OnLoadBeacon at the placement level includes the parameter action=universal, indicating that the response is using universal beacons.

Handling non-rendered products

For SKUs that were not rendered, you must append additional parameters to the universal onLoadBeaconto avoid inaccurate impression and attribution counts. Here’s how to handle unrendered products:

  1. Specify unrendered SKUs: Use the ex parameter to list the SKUs that were not rendered.

  2. Add exclusion reasons: Use the st parameter to specify the reasons for each unrendered SKU.

Example

"//b.us5.us.criteo.com/rm?fid=1205&hl_qs_cmp=UuI4LMFk...&action=univeresal&ex=17942|18980&st=3|302"

Status codes

When specifying the reasons why products did not render, use the following status codes:

Generic errors (0-99)

  • 1: Generic error (catch-all)
  • 2: Latency
  • 3: AB Testing
  • 4: Not viewable
  • 5: Invalid Traffic
  • 6: Placement/page not activated
  • 7: Opted-out user / unknown user status
  • 8: Not readable answer

Bid/Auction logic (100-199)

  • 100: Bid/auction (catch-all)
  • 101: Duplicate ad response
  • 102: Minimum SKUs requirement
  • 103: Placement already filled with other ads
  • 104: Lost to competition
  • 105: Bid too low
  • 106: Blocked buyer

Creatives (200-299)

  • 200: Creative generic (catch-all)
  • 201: Not an advertisable brand (Brand Safety)
  • 202: Not an advertisable SKU
  • 203: Not an advertisable category
  • 204: Wrong creative format (SP vs CD)
  • 205: Wrong creative format (incorrect integration in retailer website, size, etc.)

Inventory/SKU (300-399)

  • 300: Inventory (catch-all)
  • 301: SKU not recognized
  • 302: Not available in the user’s store
  • 303: Item not in stock
  • 304: SKU metadata not accurate
  • 305: Missing info (price, description, brand, rating, discount)

Relevancy/UX constraints (400-499)

  • 400: Relevancy (catch-all)
  • 401: Branded search
  • 402: Deduplication
  • 403: Returned SKUs not in retailer recommended whitelist
  • 404: Frequency capping
  • 405: Relevancy requirements not satisfied
  • 406: Geo constraints

What’s Next