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
- 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:
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)
- 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",
});
Developers Ressources
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. |