Skip to main content

Orion - Getting Started ( Manual )

This is the manual guide for getting started with Orion if you're using WordPress you can follow the WordPress guide instead or you can follow our Tag guide for a tag based implementation.

Implementing the Orion Library Manually

This guide provides concise steps for implementing the Orion.js library for on-page analytics. Orion.js collects client-side information that is reported in the Spiny app.

Prerequisites​

Bundle Reference​

Our script/bundle for Orion is included in our Pandora mono-library as a component. Ensure you reference the JavaScript bundle URL provided to you. Use the appropriate bundle for your environment: stage for exposed staging environments and prod for production environments.

The format of the JavaScript bundle URL is as follows:

https://cdn-ext.spiny.ai/lib/pa/<ENVIRONMENT>/<ORGANIZATION>/<SITE DESIGNATION>/<VARIANT>/pandora.min.js

Explanation of path parts:

  • <ENVIRONMENT>: Use stage for staging and prod for production.
  • <ORGANIZATION> (Optional): The organization designation for nesting sites. If not provided, it will be nested under sovereign.
  • <SITE DESIGNATION>: The primary portion of the host name for the site.
  • <VARIANT>: Initial value is usually default, representing the baseline bundle for your site.

Example​

The following script reference is purely an example. For this example we will use the organization ABC Group and site testsite.com.

<script async src="https://cdn-ext.spiny.ai/lib/pa/prod/abcgroup/testsite/default/pandora.min.js"></script>

Reference Attributes​

Use the following HTML script tag to reference the Pandora bundle for your site. Exclude Pandora from any plugins that perform post processing and script concatenation.

<script async src="<SCRIPT URL>"></script>

Bootstrap Code​

Place the following code snippet in the <head> of your site code. You can use the provided bootstrap script to wrap various Orion methods in window.orion.queue and add window.orion.queue to the page. window.orion.queue is an array of callbacks ran once the Orion API is ready to use.

<script>
  var orionMethods = ["init","registerElement","setConfig", "setContext","newPageView", "on"];
  (function(s,p,i,n,y){s[i]=s[i]||{queue:[]};for(var x=0;x<n.length;x++){(function(m){s[i][m]=s[i][m]||function(){var a=arguments;s[i].queue.push(function(){s[i][m].apply(s[i],a)})}})(n[x])}if(y){var e=p.createElement("script");e.type="text/javascript";e.async=true;e.src=y;var f=p.getElementsByTagName("script")[0];if(f){f.parentNode.insertBefore(e,f)}else{var d=p.getElementsByTagName("head")[0];if(d){d.appendChild(e)}}}})(window,document,"orion",orionMethods,null);
</script>

You will notice in the bootstrap code variable orionMethods which is array of function names ["init","registerElement","setConfig", "setContext","newPageView", "on"]. These functions will be made available immediately after the bootstrap code is executed allowing your site side implementation to call the Orion library as you see fit with these methods. This array of methods will change if you have additional integrations. Please keep this in mind when implementing those additional integrations.

Utilizing return values​

The bootstrap code above only works for executing functions that a return value is not needed. If you would like to utilize return values of Orion functions you will need to leverage the Orion library as show below.

<script>
  window.orion = window.orion || { queue: [] }; // Not needed if using the bootstrap code
  window.orion.queue = window.orion.queue || []; // Not needed if using the bootstrap code

  window.orion.queue.push(function(){
    // Full API of Orion is available in this scope

    const cancelListener = orion.on("adImpression.dispatched", function(eventData){
      // do something with event data
    });

    const implementationConfig = {};

    orion.init(implementationConfig);

    // Cancellation trigger logic
    cancelListener();
  })
</script>

Initialization​

For a manual integration, call orion.init(implementationRuntimeConfig) on page load. This sets/merges your runtime configuration and initializes all modules. It also triggers an initial page view event.

Important

Only call orion.init(implementationRuntimeConfig) once per client-side runtime.

For subsequent client-side page views, where client-side JavaScript renders more content or more than one page worth of data on a single server-side call, use the following verbose call when the user begins to scroll the subsequent page into view:

orion.setConfig(newPvConfig);
// or if only updating context:
orion.setContext(newPvContext);

orion.newPageView();

Ensure that setConfig or setContext is called before newPageView.

Config​

The configuration controls the behavior of the library. Usually, the static configuration for your site is handled by our team, so you don't need to make many adjustments outside of the context.

Context​

Context provides Orion with all the necessary data for proper event attribution. When setting the configuration, you can update context under the top-level context key:

orion.init({
  context: implementationContext
});

orion.setConfig({
  context: implementationContext
})

For more information about the values that can be passed into context, visit this link.

Important

Please pass all context values available on each page view. If uncertain the minimum we expect for our platform is the Page Metadata(properties where available) and Author(where available).

Implementation Code Snippet​

For all pages you will need to have the following snippet of code with any additional changes for integrations(please see our integration guides).

The following code snippets are an example only. You will need to change the values passed into the context on a per page basis.

Initial Page Views​

<!-- INSIDE <head> ELEMENT --->
<!-- Spiny.ai Pandora Bundle --->
<script async src="BUNDLE_URL"></script>

<!-- Spiny.ai Orion Bootstrap START --->
<script>

  var orionMethods = ["init","registerElement","setConfig", "setContext","newPageView", "on"];
  (function(s,p,i,n,y){s[i]=s[i]||{queue:[]};for(var x=0;x<n.length;x++){(function(m){s[i][m]=s[i][m]||function(){var a=arguments;s[i].queue.push(function(){s[i][m].apply(s[i],a)})}})(n[x])}if(y){var e=p.createElement("script");e.type="text/javascript";e.async=true;e.src=y;var f=p.getElementsByTagName("script")[0];if(f){f.parentNode.insertBefore(e,f)}else{var d=p.getElementsByTagName("head")[0];if(d){d.appendChild(e)}}}})(window,document,"orion",orionMethods,null);
  
  // The below can be called at a later point if not all data is available yet
  orion.init({
    context: {
      page: {
        contentId: "55", // If on a content entity(usually article) this would be the entity id in your database
        pageType: "article", // As defined in your onboarding analysis document for page types. Examples: "home", "category", "search", "video"
        datePosted: "2024-06-21T15:14:08+00:00",
        dateModified: "2024-06-21T15:14:08+00:00",
        wordCount: 5555, // Word count of article
        premium: false, // Whether the content is behind a paywall
        primaryCategory: { // Primary category associated to the content item, null if none
          id: "42", // ID in your database for this category
          name: "Texas Longhorns Basketball" // Category name
        },
        categories: [ // All categories associated to content the item, null if none
          {
            name: "Basketball",
            id: "11",
          },
          {
            name: "Texas",
            id: "22"
          },
          {
            name: "Texas Longhorns Basketball",
            id: "42"
          }
        ],
        keywords: [ // All keywords or tags associated to the content item, null if none
          {
            name: "Sports",
            id: "3"
          },
          {
            name: "Arthur Kaluma",
            id: "935"
          }
        ]
      },
      author: { // Author information, left out if none
        authorId: "555", // ID in your database for the author
        authorName: "John Doe" // Name as you would like the author to show up in the Spiny application
      },
      user: {
        userStatus: "guest" // User Status, generally "guest" for non-registered users, "member" for registered, "subscriber-monthly" for monthly subscribers, "subscriber-annual" for annual subscribers. These values are customizable and can be defined client side as you see fit.
      },
      channel: "Sports/Basketball/Texas/Longhorns", // If leveraging channels, null or left out if not using channels
    }
  })
</script>
<!-- Spiny.ai Orion Bootstrap END --->

Subsequent Dynamic Page Views​

When you add new content to a webpage using JavaScript, and you've already started orion.init(), you should use this code as the new content appears on the screen(active viewport) for the end user. This is common in situations like infinite scroll articles or when navigating pages in next.js.

<script>
  orion.setContext({
    context: {
      page: {
        contentId: "55", // If on a content entity(usually article) this would be the entity id in your database
        pageType: "article", // As defined in your onboarding analysis document for page types. Use the current page's expected page type. Examples: "home", "category", "search", "video"
        datePosted: "2024-06-21T15:14:08+00:00",
        dateModified: "2024-06-21T15:14:08+00:00",
        wordCount: 5555, // Word count of article
        premium: false, // Whether the content is behind a paywall
        primaryCategory: { // Primary category associated to the content item, null if none
          id: "42", // ID in your database for this category
          name: "Texas Longhorns Basketball" // Category name as you would like to see it in the Spiny application
        },
        categories: [ // All categories associated to content the item, null if none
          {
            name: "Basketball",
            id: "11",
          },
          {
            name: "Texas",
            id: "22"
          },
          {
            name: "Texas Longhorns Basketball",
            id: "42"
          }
        ],
        keywords: [ // All keywords or tags associated to the content item, null if none
          {
            name: "Sports",
            id: "3"
          },
          {
            name: "Arthur Kaluma",
            id: "935"
          }
        ]
      },
      author: { // Author information
        authorId: "555", // ID in your database for the author
        authorName: "John Doe" // Name as you would like the author to show up in the Spiny application
      },
      user: {
        userStatus: "guest" // User Status, generally "guest" for non-registered users, "member" for registered, "subscriber-monthly" for monthly subscribers, "subscriber-annual" for annual subscribers. These values are customizable and can be defined client side as you see fit.
      },
      channel: "Sports/Basketball/Texas/Longhorns", // If leveraging channels, null or left out if not using channels
    }
  });

  orion.newPageView();
</script>

Third Party Integrations​

To ensure complete reporting please be sure to follow the guides under integrations in the sidebar for any third party ad integrations you have.