Skip to main content

Orion - Getting Started ( Tag )

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

Implementing the Orion Library via a Tag

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.

Additional Requirements​

For Orion to automatically pull in various metadata accurately for your site there are several additional requirements outlined below.

Requirements:

  • Structured Data - JSON-LD Variant
  • Spiny Meta Tags - Optional
  • Canonical URLs
  • On websites where client side navigation to new pages is present (such as infinite scroll or with next.js) the above need to be updated upon navigation to reflect the current page view's metadata.

The Page View Event​

Tag manager specific bundles are built with the initial page view occurring after Orion is automatically initialized which by default will occur after the DOMContentLoaded event.

Client Side Page Navigation​

There are two strategies we can configure for your bundle( you can only have one per bundle ).

Automatically Detect New Page Views ( Default )​

Subsequent page views are detected by mutations/rerenders to/of the canonical url element(link[rel="canonical"]). It is important to note that all updates to structured data and/or spiny meta tags must occur prior to the canonical url changing. Once the canonical url is updated Orion will reparse metatags and structured data and apply it to the Orion context.

Manual Invocation of New Page Views​

Leveraging this strategy will allow you to override structured data inference and Spiny meta tags but you will have to call orion.newPageView() for every client side page navigation.

Structured Data Inference​

In addition to the data we gather automatically we infer the following context values from structured data.

  • Page Type (page.pageType)
    • article where the presence of an supported article schema is detected.
    • course where the presence of a Course schema is detected.
    • recipe where the presence of a Recipe schema is detected.
    • podcast-episode where the presence of a PodcastEpisode schema is detected.
  • Premium Content (page.premium)
  • Primary Category (page.primaryCategory)
    • Mapped directly to supported article schemas' property articleSection. If an array we take the first item in the array as the primary category.
  • Author ( author.authorName )
    • Taken from the author.name property of any of the supported creative work schemas. If an array we take the first author's name. At this time we support a single author per content item but will in the future support multiple.
  • Keywords ( page.keywords )
  • Date Posted ( page.datePosted )
  • Date Modified ( page.dateModified )
  • Word Count ( page.wordCount )
Setting Inferred Contexts Directly

Only applies with automatic page view detection specified here.

The only manner in which to override the automatically inferred values above is through usage of Spiny Meta Tags defined below. Attempting to set/override context values with manual calls to orion.setContext(newContext) or any other methods will result in the value being overridden by inferred values once the next page view is detected via a canonical url change. This only applies to inferred context values. If setting values such as network, channel, or any of the values not documented above they will not be overridden by inferred values.

Example​

On Page Structured Data. While this example leverages @graph, non-graph specifications for these schemas will operate as intended as well.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "NewsArticle",
      "@id": "https://www.on3.com/news/college-football-player-rankings-jeremiah-smith-ryan-williams-headline-on3-impact-top-10-wrs-after-week-5/#article",
      "isPartOf": {
        "@id": "https://www.on3.com/news/college-football-player-rankings-jeremiah-smith-ryan-williams-headline-on3-impact-top-10-wrs-after-week-5/"
      },
      "author": {
        "name": "Nick Kosko",
        "@id": "https://www.on3.com/#/schema/person/b09f6790f9ed84f1653ee7625235fc3f"
      },
      "headline": "College Football Player Rankings: Jeremiah Smith, Ryan Williams headline On3 Impact Top 10 WRs after Week 5",
      "datePublished": "2024-10-02T20:19:57+00:00",
      "dateModified": "2024-10-02T20:20:10+00:00",
      "mainEntityOfPage": {
        "@id": "https://www.on3.com/news/college-football-player-rankings-jeremiah-smith-ryan-williams-headline-on3-impact-top-10-wrs-after-week-5/"
      },
      "wordCount": 765,
      "isAvailableForFree": false,
      "commentCount": 0,
      "publisher": { "@id": "https://www.on3.com/#organization" },
      "image": {
        "@id": "https://www.on3.com/news/college-football-player-rankings-jeremiah-smith-ryan-williams-headline-on3-impact-top-10-wrs-after-week-5/#primaryimage"
      },
      "thumbnailUrl": "https://on3static.com/uploads/dev/assets/cms/2024/10/02095612/On3-Impact-Top-10-WRs.png",
      "keywords": [
        "Emeka Egbuka (21 - Steilacoom)",
        "Jeremiah Smith (24 - Chaminade-Madonna Prep)",
        "Luther Burden (22 - East St. Louis)",
        "Ryan Williams (24 - Saraland)",
        "Tai Felton (21 - Stone Bridge)",
        "Tetairoa McMillan (22 - Servite)",
        "Tez Johnson (20 - Pinson Valley)",
        "Travis Hunter (22 - Collins Hill)",
        "Tre Harris (20 - Comeaux)",
        "Xavier Restrepo (20 - Deerfield Beach)"
      ],
      "articleSection": [
        "Alabama Crimson Tide",
        "Alabama Crimson Tide Football",
        "Arizona Wildcats",
        "Arizona Wildcats Football",
        "Colorado Buffaloes",
        "Colorado Buffaloes Football",
        "Maryland Terrapins",
        "Maryland Terrapins Football",
        "Miami Hurricanes",
        "Miami Hurricanes Football",
        "Missouri Tigers",
        "Missouri Tigers Football",
        "Ohio State Buckeyes",
        "Ohio State Buckeyes Football",
        "Ole Miss Rebels",
        "Ole Miss Rebels Football",
        "On3",
        "On3 Football",
        "Oregon Ducks",
        "Oregon Ducks Football"
      ],
      "inLanguage": "en-US",
      "potentialAction": [
        {
          "@type": "CommentAction",
          "name": "Comment",
          "target": [
            "https://www.on3.com/news/college-football-player-rankings-jeremiah-smith-ryan-williams-headline-on3-impact-top-10-wrs-after-week-5/#respond"
          ]
        }
      ],
      "copyrightYear": "2024",
      "copyrightHolder": { "@id": "https://www.on3.com/#organization" }
    }
  ]
}
</script>

Would translate to the following context inference:

{
  "page": {
    "pageType": "article",
    "premium": true,
    "primaryCategory": { "name": "Alabama Crimson Tide" },
    "keywords": [
      { "name": "Emeka Egbuka (21 - Steilacoom)" },
      { "name": "Jeremiah Smith (24 - Chaminade-Madonna Prep)" },
      { "name": "Luther Burden (22 - East St. Louis)" },
      { "name": "Ryan Williams (24 - Saraland)" },
      { "name": "Tai Felton (21 - Stone Bridge)" },
      { "name": "Tetairoa McMillan (22 - Servite)" },
      { "name": "Tez Johnson (20 - Pinson Valley)" },
      { "name": "Travis Hunter (22 - Collins Hill)" },
      { "name": "Tre Harris (20 - Comeaux)" },
      { "name": "Xavier Restrepo (20 - Deerfield Beach)" }
    ],
    "datePosted": "2024-10-02T20:19:57+00:00",
    "dateModified": "2024-10-02T20:20:10+00:00",
    "wordCount": 765
  },
  "author": { "authorName": "Nick Kosko" }
}

Supported Article Schemas​

Supported Creative Work Schemas​

Supported Creative Work Schemas Expanded​

Spiny Meta Tags​

Values that are automatically inferred from the page can be overridden via Spiny meta tags and we strongly recommend including one specific meta tag on all of your content pages. The content ID meta tag. The content value in the meta tag below should reflect a unique ID from your own database system that corresponds to that specific content item and will not be changed in the future. If the value does change it will be considered a separate content item.

<meta property="spiny:page:contentId" content="<UNIQUE_CONTENT_ID>">

If you have multiple content types it may be preferred to prefix the id with the content type.

<meta property="spiny:page:contentId" content="<CONTENT_TYPE>-<UNIQUE_CONTENT_ID>">

<!-- EXAMPLE -->
<meta property="spiny:page:contentId" content="podcast-555">

You can specify any of Orion's context values as a meta tag and these values will override any data we gather automatically. Simply delimit the nested property path with colons and prefixed with spiny:. Examples below.

<!-- Setting Page Type ( Orion context path: page.pageType ) -->
<meta property="spiny:page:pageType" content="slideshow">

<!-- Setting Channel ( Orion context path: channel ) -->
<meta property="spiny:channel" content="football/nfl/titans">

<!-- Setting Network Domain ( Orion context path: network.domain ) -->
<meta property="spiny:network:domain" content="subsite-1">

<!-- Setting array value page keywords ( Orion context path: page.keywords ) -->
<meta property="spiny:page:keywords:name" content="keyword1">
<meta property="spiny:page:keywords:id" content="5551">
<meta property="spiny:page:keywords:name" content="keyword2">
<meta property="spiny:page:keywords:id" content="5552">

Client Side Page Navigations​

Please be sure to remove/update any specified meta tags when a client side navigation occurs as they will be re-parsed once the canonical URL element is changed.

New Page View detection

Only applies with automatic page view detection specified here.

A mutation observer will be setup observing the canonical url element link[rel="canonical"] for changes or re-rendering. Please ensure structured data and spiny meta tags are updated prior to the canonical url element being updated.

The Tag​

Important

Please ensure our script is included at the top level and not within a nested iframe.

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 = ["setConfig", "setContext","newPageView"];
  (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 ["setConfig", "setContext","newPageView"]. 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.

Full Code Snippet​

Place the following with your bundle url for the script source in the <head> of your site or to be loaded in with your tag manager scripts.

<script async src="https://cdn-ext.spiny.ai/lib/pa/prod/abcgroup/testsite/default/pandora.min.js"></script>
<script>
  var orionMethods = ["setConfig", "setContext","newPageView"]; // Will potentially be different based on third party integrations
  (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>

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.