Attributions

The attribution functionality enables you to attribute valuable behavior outside the scope of an immersive experience to an immersive session.

As an example, if you have a link to a merchandise store inside your VR/AR/MR experience, you could collect data on whether or not the user purchases something in the store, and attach that data to a specific session.

This works by sending an attribution event to the Cognitive3D data collector via a JavaScript function. The event contains the Session ID, Scene Version ID, the Attribution Key, and a properties object that you can add personalized data to.

Adding the script to your site

The script is hosted and available from Cognitive3D. We recommend calling the script from our server directly to ensure the latest version is being run on your application. If you wish to host it yourself, please contact us to discuss.

Script Location: https://cognitive3d.com/scripts/attr.min.js

The un-minified version of the script is also available here for your reference: https://cognitive3d.com/scripts/attr.js

Passing data from the SDK

In order to send attribution events, you need to pass three pieces of data from the SDK: The attribution key for authentication, the Session ID, and the Scene Version ID. This information will get passed as a Base-64 encoded JSON String in the URL as a query parameter labeled c3dAtkd.

Here’s an example of what the JSON string will look like:

{
  "sessionId": "abcdef",
  "sceneVersionId": "123456",
  "attributionKey": "qwerty"
}

Once the data is Base64 encoded, it will look like this

ewogICJzZXNzaW9uSWQiOiAiYWJjZGVmIiwKICAic2NlbmVWZXJzaW9uSWQiOiAiMTIzNDU2IiwKICAiYXR0cmlidXRpb25LZXkiOiAicXdlcnR5Igp9

That Base64 encoded string should then be prefixed with AK- and sent in the URL as c3dAtkd.

Here’s an example of what the final URL should look like:

https://www.oakley.com/en-us/product/W0OO9384?c3dAtkd=AK-ewogICJzZXNzaW9uSWQiOiAiYWJjZGVmIiwKICAic2NlbmVWZXJzaW9uSWQiOiAiMTIzNDU2IiwKICAiYXR0cmlidXRpb25LZXkiOiAicXdlcnR5Igp9

Creating properties

Properties are a javascript object that contains any data you want to attach to the attribution event. It can contain any number of keys and values, but it must not contain any other objects or arrays.

const c3dEventProperties = {
  label: "Example Label",
  description: "Properties can contain whatever data suits your needs best, as long as it doesn't contain objects or arrays!",
  userId: 123456
}

Sending the attribution event

Once you have a properly formatted URL with the c3dAtkd query parameter, imported the data collector script, and created a properties object, sending the attribution event to the Cognitive3D Data Collector is as easy as calling the c3dAttributionEvent function. Simply pass your properties object as a parameter.

c3dAttributionEvent(c3dEventProperties);

Adding a custom event name

If you want, you can save your attribution event with a custom event name, overriding the default c3d.attributionEvent. All you have to do is pass a second parameter to the function.

c3dAttributionEvent(c3dEventProperties, 'Custom Event Name');

Optional Error Handling

The c3dAttributionEvent will work just fine by calling it by itself, without any additional code. However, if there’s an error parsing/sending the data, it will silently fail. You can optionally receive the data collector response to validate that it actually goes through. The function returns a promise that will either reject if there’s an error parsing the data from your properties object or query parameter- or it will succeed with the data collector response. The data collector will respond with a 204 status if the event has been successfully uploaded. Here’s an example of what this would look like:

// Uploads the data to the data collector
c3dAttributionEvent(c3dEventProperties, 'Custom Event Name').then(res => {

  // You can then check the response from the POST request in here.
  // The Cognitive3D data collector will return a 204 No Content if
  // the data is successfully uploaded
  if (res.status !== 204) {
    console.log("something went wrong!");
    // Handle error
  }

}).catch(e => console.warn(e));

Examples

Here will be two full examples of what the HTML file will look like. The first one will be a simple example if you don’t need advanced error handling and the second will be a more advanced use-case.

In our example, our user clicked on a 3D product placement from a mixed reality app, has been taken to the Oakley store, and has added a product to their cart.

Simple Example

https://www.oakley.com/en-us/product/W0OO9384?c3dAtkd=AK-ewogICJzZXNzaW9uSWQiOiAiYWJjZGVmIiwKICAic2NlbmVWZXJzaW9uSWQiOiAiMTIzNDU2IiwKICAiYXR0cmlidXRpb25LZXkiOiAicXdlcnR5Igp9

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Oakley Product Purchase Example</title>
</head>
<body>

  <!-- Load the Cognitive3D Attribution script -->
  <script src="https://cognitive3d.com/scripts/attr.min.js"></script>
  <script>
    // Create the properties object that will contain the data that gets sent to the Cognitive3D data collector
    const c3dEventProperties = {
      label: "Add to Cart",
      itemName: "Holbrook Mix",
      itemSku: "OO9384-0457",
      itemValue: "148.80",
      userId: 123456
    }

    // Uploads the data to the data collector
    c3dAttributionEvent(c3dEventProperties); 
  </script>

</body>
</html>

Advanced Example

https://www.oakley.com/en-us/product/W0OO9384?c3dAtkd=AK-ewogICJzZXNzaW9uSWQiOiAiYWJjZGVmIiwKICAic2NlbmVWZXJzaW9uSWQiOiAiMTIzNDU2IiwKICAiYXR0cmlidXRpb25LZXkiOiAicXdlcnR5Igp9

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Oakley Product Purchase Example</title>
</head>
<body>

  <!-- Load the Cognitive3D Attribution script -->
  <script src="https://cognitive3d.com/scripts/attr.min.js"></script>
  <script>
    // Create the properties object that will contain the data that gets sent to the Cognitive3D data collector
    const c3dEventProperties = {
      label: "Add to Cart",
      itemName: "Holbrook Mix",
      itemSku: "OO9384-0457",
      itemValue: "148.80",
      userId: 123456
    }

    // Uploads the data to the data collector
    c3dAttributionEvent(c3dEventProperties, 'OakleyAttribution').then(res => {
      // You can then check the response from the POST request in here.
      // The Cognitive3D data collector will return a 204 No Content if
      // the data is successfully uploaded
      if (res.status !== 204) {
        console.log("something went wrong!");
        // Handle error or retry request
      }

    }).catch(e => {
      console.warn(e);
      // Handle error or retry request
    });
  </script>

</body>
</html>

If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page.