Installation Guide

Before You Begin

Before integrating the SDK, gather the following information:

Locate the integration settings page in your dashboard
Gather these values:
- INTEGRATION-ID: Your unique publisher ID
- INTEGRATION-TYPE: Your pixel type identifier

Note: Contact your account manager if you don't have these credentials.

Prerequisites

Modern browser (Chrome 80+, Firefox 75+, Safari 13+, Edge 80+)
HTTPS enabled on your website (required for production)

CDN Installation

Place the SDK script in the <head> tag for earliest loading:

<script type="text/javascript">
  !(function (s) {
    var o = s.createElement('script'),
      u = s.getElementsByTagName('script')[0];
    o.src = 'https://cdn.aggle.net/oir/oir.min.js';
    o.async = !0;
    o.setAttribute('oirtyp', 'REPLACE_WITH_INTEGRATION_TYPE');
    o.setAttribute('oirid', 'REPLACE_WITH_INTEGRATION_ID');
    u.parentNode.insertBefore(o, u);
  })(document);
</script>

Note: The complete snippet code may be available on your integration settings page. Just copy and paste it into your <head> tag.

Script Attributes

The following options can be set via script attributes:

Attribute	Required	Description
`oirid`	✅	Your unique publisher ID
`oirtyp`	✅	Pixel type identifier

Additional Configuration

For configuration options not supported via attributes (e.g., brandedLinkDomain), call the cfg() method after the SDK loads:

<script type="text/javascript">
  !(function (s) {
    var o = s.createElement('script'),
      u = s.getElementsByTagName('script')[0];
    o.src = 'https://cdn.aggle.net/oir/oir.min.js';
    o.async = !0;
    o.setAttribute('oirtyp', 'REPLACE_WITH_INTEGRATION_TYPE');
    o.setAttribute('oirid', 'REPLACE_WITH_INTEGRATION_ID');

    // Additional configuration after SDK loads
    o.onload = function () {
      var config = {
        brandedLinkDomain: 'track.yourdomain.com',
      };

      // Use cfg() if SDK is loaded, otherwise push to queue
      if (window._oirtrk && typeof window._oirtrk.cfg === 'function') {
        window._oirtrk.cfg(config);
      } else {
        window._oirtrk = window._oirtrk || [];
        window._oirtrk.push(['cfg', config]);
      }
    };

    // Optional: error handling
    o.onerror = function () {
      console.warn('OIR SDK failed to load');
    };

    u.parentNode.insertBefore(o, u);
  })(document);
</script>

See the Configuration Guide for all available options.

Verify Installation

After installation, verify the SDK is loaded:

if (typeof window._oirtrk !== 'undefined') {
  console.log('SDK loaded successfully');
  console.log('Version:', window._oirtrk.version());
}

Performance Best Practices

Optimize SDK loading to minimize impact on page performance.

1. Default Async Loading (Recommended)

The standard installation uses async loading, which is recommended for most use cases:

o.async = !0; // Script loads asynchronously, doesn't block page rendering

Benefits:

Does not block page rendering
Page loads quickly while SDK loads in background
Events are queued until SDK is ready

2. Preload the Script

For faster SDK availability, add a preload hint in your <head>:

<link rel="preload" href="https://cdn.aggle.net/oir/oir.min.js" as="script" />

Benefits:

Browser starts downloading the script earlier
Reduces time to SDK availability
No impact on page rendering

3. DNS Prefetch

If using a first-party tracking domain, add DNS prefetch:

<link rel="dns-prefetch" href="//track.yourdomain.com" />
<link rel="preconnect" href="https://track.yourdomain.com" />

Benefits:

Resolves DNS before tracking requests are made
Reduces latency for first tracking call

4. Lazy Loading (Advanced)

For pages where tracking is less critical, load the SDK after the page is fully loaded:

<script type="text/javascript">
  window.addEventListener('load', function () {
    !(function (s) {
      var o = s.createElement('script'),
        u = s.getElementsByTagName('script')[0];
      o.src = 'https://cdn.aggle.net/oir/oir.min.js';
      o.async = !0;
      o.setAttribute('oirtyp', 'YOUR_INTEGRATION_TYPE');
      o.setAttribute('oirid', 'YOUR_INTEGRATION_ID');
      u.parentNode.insertBefore(o, u);
    })(document);
  });
</script>

Benefits:

Zero impact on initial page load
Ideal for content-focused pages

Trade-offs:

May miss early user interactions
Page view event fires later

5. Conditional Loading

Load the SDK only when needed (e.g., based on user consent):

function loadOIRSDK() {
  if (window._oirtrk) return; // Already loaded

  !(function (s) {
    var o = s.createElement('script'),
      u = s.getElementsByTagName('script')[0];
    o.src = 'https://cdn.aggle.net/oir/oir.min.js';
    o.async = !0;
    o.setAttribute('oirtyp', 'YOUR_INTEGRATION_TYPE');
    o.setAttribute('oirid', 'YOUR_INTEGRATION_ID');
    u.parentNode.insertBefore(o, u);
  })(document);
}

// Load after user consent
document.getElementById('accept-cookies').addEventListener('click', loadOIRSDK);

Performance Checklist

Use async loading (default)
Add preload hint for critical pages
Use DNS prefetch for custom domains
Consider lazy loading for non-critical pages
Test with browser DevTools to verify loading impact

Implementation Best Practices

Follow this recommended order when setting up the SDK on your webpage.

Recommended Setup Order

<!-- 1. Preload hint (optional, for better performance) -->
<link rel="preload" href="https://cdn.aggle.net/oir/oir.min.js" as="script" />

<!-- 2. Initialize queue before SDK loads -->
<script type="text/javascript">
  window._oirtrk = window._oirtrk || [];
</script>

<!-- 3. Set global custom data early (before SDK loads) -->
<script type="text/javascript">
  // Set any known data immediately - these will be queued
  window._oirtrk.push(['set', 'puid', '12345']);
  window._oirtrk.push(['set', 'campaignId', 'summer_2024']);
</script>

<!-- 4. Load the SDK with configuration -->
<script type="text/javascript">
  !(function (s) {
    var o = s.createElement('script'),
      u = s.getElementsByTagName('script')[0];
    o.src = 'https://cdn.aggle.net/oir/oir.min.js';
    o.async = !0;
    o.setAttribute('oirtyp', 'YOUR_INTEGRATION_TYPE');
    o.setAttribute('oirid', 'YOUR_INTEGRATION_ID');

    // 5. Additional configuration after load
    o.onload = function () {
      var config = {
        autoPageView: true, // Enable automatic page view tracking (default)
        // brandedLinkDomain: 'track.yourdomain.com',  // Optional: First-party tracking
      };

      if (window._oirtrk && typeof window._oirtrk.cfg === 'function') {
        window._oirtrk.cfg(config);
      } else {
        window._oirtrk.push(['cfg', config]);
      }
    };

    u.parentNode.insertBefore(o, u);
  })(document);
</script>

Step-by-Step Breakdown

Step	Action	Purpose
1	Preload hint	Browser starts downloading SDK early
2	Initialize queue	Allows commands before SDK loads
3	Set global custom data	Data is queued and applied to all events
4	Load SDK with attributes	Required `oirid` and `oirtyp`
5	Configure on load	Set additional options like `autoPageView`

Key Recommendations

1. Initialize the Queue Early

Always initialize the queue before any tracking calls:

window._oirtrk = window._oirtrk || [];

2. Set Global Data Before SDK Loads

Global custom data set before the SDK loads will be applied to all events, including the automatic page view:

// These are queued and processed when SDK initializes
window._oirtrk.push(['set', 'puid', getUserId()]);
window._oirtrk.push(['set', 'sessionId', getSessionId()]);

3. Use Script Attributes for Required Config

Always use script attributes for oirid and oirtyp:

o.setAttribute('oirtyp', 'YOUR_INTEGRATION_TYPE');
o.setAttribute('oirid', 'YOUR_INTEGRATION_ID');

4. Use `onload` for Optional Config

Configure optional settings after the SDK loads:

o.onload = function () {
  window._oirtrk.cfg({
    autoPageView: true,
    brandedLinkDomain: 'track.yourdomain.com',
  });
};

5. Handle Dynamic Data

For data that becomes available later (e.g., after user action), use the set command anytime:

// After user logs in
window._oirtrk.push(['set', 'userType', 'premium']);

// After fetching user preferences
window._oirtrk.push(['set', 'preferredLanguage', userPrefs.language]);

Implementation Checklist

Queue initialized before SDK loads
Global custom data set as early as possible
Required attributes (oirid, oirtyp) set on script
Optional configuration in onload callback
autoPageView configured as needed
Error handling with onerror callback (optional)

Troubleshooting

SDK not loading?

Verify the CDN URL is correct
Check browser console for errors
Ensure HTTPS is used in production
Check that no ad blockers are blocking the script

Script attributes not working?

Ensure attributes are set before script insertion
Verify oirid and oirtyp values are correct

Next Steps

Configuration Guide - Configure additional SDK options
Quick Start Guide - Track your first event
Custom Events Guide - Track custom business events

Installation Guide

Learn how to install the OIR SDK on your website.

Before You Begin

Prerequisites

CDN Installation

Script Attributes

Additional Configuration

Verify Installation

Performance Best Practices

1. Default Async Loading (Recommended)

2. Preload the Script

3. DNS Prefetch

4. Lazy Loading (Advanced)

5. Conditional Loading

Performance Checklist

Implementation Best Practices

Recommended Setup Order

Step-by-Step Breakdown

Key Recommendations

1. Initialize the Queue Early

2. Set Global Data Before SDK Loads

3. Use Script Attributes for Required Config

4. Use onload for Optional Config

5. Handle Dynamic Data

Implementation Checklist

Troubleshooting

SDK not loading?

Script attributes not working?

Next Steps

4. Use `onload` for Optional Config