Developers - Oversite
Oversite
Installation
To install the Perfection tools in your application, you can use the Oversite NPM package.
Install the NPM package as follows:
- Npm
- Yarn
- Pnpm
- Bun
- Script
- Google Tag Manager
npm install @perfectiondev/oversite
yarn add @perfectiondev/oversite
pnpm i @perfectiondev/oversite
bun add @perfectiondev/oversite
<script src="https://unpkg.com/@perfectiondev/oversite@latest/dist/index.iife.js"></script>
To install Perfection with Google Tag Manager, create a new Custom HTML tag that is triggerred on any Page View.
Please don't forget to update apiKey, subscription and site with your credentials. (See next chapter).
<script>
var head = document.getElementsByTagName("head")[0];
var js = document.createElement("script");
js.src = "https://unpkg.com/@perfectiondev/oversite@latest/dist/index.iife.js";
head.appendChild(js);
js.onload = function () {
if ("oversite" in window)
window.oversite.initialize({
apiKey: "{{Perfection API Key}}",
subscription: "{{Perfection Subscription Id}}",
site: "{{Perfection Site Name}}",
});
};
</script>
Here is what you should see in Google Tag Manager:
Follow this tutorial to generate your API Key and retrieve your Subscription ID from the Admin Panel.
Initialize Oversite
- Next.js (App Router)
- Nuxt
- JavaScript
To store your Perfection's Site Name, API Key and Subscription ID, you can create an .env.local file that should be localted at the root folder of your project. Once you have this set, you can initialize Oversite as follow:
"use client";
import oversite from "@perfectiondev/oversite";
export default function Oversite() {
oversite.initialize({
apiKey: process.env.NEXT_PUBLIC_PERFECTION_API_KEY,
subscription: process.env.NEXT_PUBLIC_PERFECTION_SUBSCRIPTION_ID,
site: process.env.NEXT_PUBLIC_PERFECTION_SITE_NAME,
});
}
As Oversite is using browser APIs, you need to use ssr option to disable server-rendering.
Make sure you dynamically load Oversite component as follow: (read more details here)
import dynamic from "next/dynamic";
/** Dynamically load Oversite without SSR, only way to get access to browser APIs needed by Oversite */
export default dynamic(() => import("./oversite"), {
ssr: false,
});
Lastly, you need to load Oversite into your pages. We recommend you doing that at Root layout or Template level:
import Oversite from "./components/OversiteNoSSR";
export default function Template({ children }) {
return <Oversite />; //Must only be mounted on your preview enviroment
}
To store your Perfection's Site Name, API Key and Subscription ID, you can create an .env file that should be localted at the root folder of your project. Once you have this set, you can initialize Oversite in oversite.client.js placed in the Nuxt plugins/ folder
import oversite from "@perfectiondev/oversite";
export default function Oversite() {
oversite.initialize({
apiKey: import.meta.env.VITE_PUBLIC_PERFECTION_API_KEY,
subscription: import.meta.env.VITE_PUBLIC_PERFECTION_SUBSCRIPTION_ID,
site: import.meta.env.VITE_PUBLIC_PERFECTION_SITE_NAME,
});
}
As Oversite is using browser APIs, you need to make sure you have .client suffix in the file name to load a plugin only on the client side. (read more details here)
if ("oversite" in window)
window.oversite.initialize({
apiKey: "YOUR_API_KEY",
subscription: "YOUR_SUBSCRIPTION_ID",
site: "YOUR_SITE_NAME",
});