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. In this implementation Spiny's Orion library will automatically infer values from pre-existing on-page values, primarily Structured Data without the need for specification of additional properties via JavaScript calls or otherwise.

Implementing the Orion Library via a Tag

This guide provides 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​

Additional Requirements​

In addition to our General Orion Prerequisites for this implementation we require additional details to be present for Orion to automatically pull in as well as potential adjustments to updating metadata prior to client side navigations.

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​

Bundles for tag implementation are built with the initial page view occurring after Orion is automatically initialized(which by default will occur after the DOMContentLoaded event). There is no need to call orion.init(orionConfig);

Client Side Page Navigation​

There are two strategies we can configure for your bundle( you can only have one per bundle ). If you would like to manually invoke page views for client side navigations please let the Spiny team know.

Automatically Detect New Page Views ( Default )​

Subsequent page views are detected by mutations/rerenders to/of the canonical url element(link[rel="canonical"]).

Automatic Page View Detection Note

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 / structured data, apply it to the Orion context, and immediately send off the page view event.

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.

Supported Article Schemas​

Supported Creative Work Schemas​

Supported Creative Work Schemas Expanded​

Example​

Below you will find an example of one article's 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" }
}

Spiny Meta Tags​

Values that are automatically inferred from the page can be overridden via Spiny meta tags.

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 prefix 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">
Recommended Spiny Meta Tag

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">

The Tag​

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​

Important

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

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. The code for this snippet can be different based on what third party integrations you are implementing.

<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.