Get Started - Tutorial

Prerequisites

Install Oversite

To add the Perfection tools to your applications, you can install Oversite via an NPM package, load it as a script or inject it via Google Tag Manager:

Npm

>_ Terminal

npm install @perfectiondev/oversite

Yarn

>_ Terminal

yarn add @perfectiondev/oversite

Pnpm

>_ Terminal

pnpm i @perfectiondev/oversite

Bun

>_ Terminal

bun add @perfectiondev/oversite

Script

page.html

<script src="https://unpkg.com/@perfectiondev/oversite@latest/dist/index.iife.js"></script>

Google Tag Manager

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

Custom HTML Tag

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

Get an API Key

Before you start configuring Perfection, you need to login in to the Admin Panel. By doing so, you will be able to invite users and generate an API Key.

If you don't have access to Perfection yet and need an account, get in touch with us through this contact us form.

API Keys, used to access the Perfection APIs, can be managed under the Settings section of the Perfection Admin Panel

Initialize Oversite

Next.js (App Router)

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:

app/components/oversite.js

"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,
  });
}

info

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)

app/components/oversiteNoSSR.js

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:

app/template.js

import Oversite from "./components/OversiteNoSSR";

export default function Template({ children }) {
  return <Oversite />; //Must only be mounted on your preview enviroment
}

Nuxt

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

plugins/oversite.client.js

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,
  });
}

info

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)

JavaScript

page.html

if ("oversite" in window)
  window.oversite.initialize({
    apiKey: "YOUR_API_KEY",
    subscription: "YOUR_SUBSCRIPTION_ID",
    site: "YOUR_SITE_NAME",
  });

Developers Ressources

• How to initialize Oversite script on a project
• Perfection Playground on Github

Terminology

Term	Description
Oversite	Oversite overlays your preview site with our Dock and others UI elements that provide access to Perfection features.
Admin Panel	The Admin Panel is the place where you manage all your Perfection features at https://app.perfection.dev/
CLI	The Perfection CLI is a Command Line Interface for interacting with Perfection's SaaS infrastructure, such as to synchronize configuration files.
SaaS	Software-as-a-Service. You don't install Perfection to your infrastructure; your pages and users access Perfection's infrastructure.
Providers	You use the Admin Panel or CLI to configure providers, which abstract access to your back-end systems such as CMS and commerce.
Themes	Themes define the features available to users for controlling page presentation options.
API	Perfection's service API exposes all functionality through a RESTful programming interface.
Deep Links	Clicking a deep link in the preview version of the website opens the underlying record in the source system, such as CMS or commerce.