adcontrolx-lib
v1.1.7
Published
React component library for Kevel ads
Downloads
151
Readme
AdControlX
A React library for serving Kevel ads.
Table of Contents
Installation
To install AdControlX, run the following command:
npm i adcontrolx-lib
Note: AdControlX is currently a public npm library, but it may become private in the future.
Usage
Important Note about PortraitTracker
AdControlX relies on the presence of PortraitTracker to correctly serve ads. Most sites in the OG already have PortraitTracker enabled.
If you are working on a new site, you will need to add PortraitTracker at the root of the application so that all pages have access to the DataLayer.
The following sections explain how to enable PortraitTracker based on the type of application you're working on.
Next.js Applications
PortraitTracker
Next.js provides the <Script /> component, which should be used just below the <body> tag in the RootLayout.
Example:
<Script src="https://portrait-tracker.s3.amazonaws.com/all.js" />
KevelProvider
The KevelProvider component wraps your project and provides site-wide access to Kevel decisions.
KevelProvider requires networkId and siteId props to make calls to the OG's Kevel account and return ads specific to your site:
- networkId identifies our organization and will be the same across all applications.
- siteId differentiates your application from the other platforms and websites in our Kevel network. This value will be unique to your application.
Example:
// This will be in your layout.js file
'use client'
export const dynamic = 'force-dynamic'
import { KevelProvider } from 'adcontrolx-lib/dist/context/kevelContext'
export default function MyLayout({ children }) {
return (
<KevelProvider networkId={123456} siteId={1234567}>
<h1>TEST Layout</h1>
{children}
</KevelProvider>
)
}AdZone
The AdZone component takes in two props to display ads: zoneId and adType.
- zoneId is a placement ID that can include or exclude certain flights/creatives. This allows you to target specific flights to a certain zone but not others.
- adType is tied to the ad's size and ensures the correct ad is displayed for each placement.
A list of zone IDs can be found in Kevel's Inventory tab.
AdZone must only be rendered on the client side. Since Next.js relies on server-side rendering, you need to ensure AdZone is rendered client-side only, as shown below:
// This will be in your page.js file
'use client'
import dynamic from 'next/dynamic'
const AdZone = dynamic(
() => import('adcontrolx-lib').then((mod) => mod.AdZone),
{ ssr: false }
)
export default function Page() {
return (
<>
<h1>Hello, TEST page!</h1>
<AdZone zoneId={123456} adType={1234} />
</>
)
}Results! 🎉
With PortraitTracker, KevelProvider, and AdZone all set up, you should now be able to see ads!
You can see test ads by adding the query parameter ?testing=yes to the end of your URL.
Client-side React Applications
PortraitTracker
For client-side React applications, adding PortraitTracker is very easy. Simply add this <script> on your index.html file.
Example:
<script src="https://portrait-tracker.s3.amazonaws.com/all.js"></script>
KevelProvider
The KevelProvider component wraps your project and provides site-wide access to Kevel decisions.
KevelProvider requires networkId and siteId props to make calls to the OG's Kevel account and return ads specific to your site:
- networkId identifies our organization and will be the same across all applications.
- siteId differentiates your application from the other platforms and websites in our Kevel network. This value will be unique to your application.
// main.jsx
import App from './App.jsx'
import './index.css'
import { KevelProvider } from 'adcontrolx-lib/dist/context/kevelContext'
createRoot(document.getElementById('root')).render(
<KevelProvider networkId={123456} siteId={1234567}>
<App />
</KevelProvider>
)AdZone
The AdZone component takes in two props to display ads: zoneId and adType.
- zoneId is a placement ID that can include or exclude certain flights/creatives. This allows you to target specific flights to a certain zone but not others.
- adType is tied to the ad's size and ensures the correct ad is displayed for each placement.
A list of zone IDs can be found in Kevel's Inventory tab.
import './App.css'
import AdZone from './components/AdZone'
function App() {
return (
<>
<h1>Hello, TEST app!</h1>
<AdZone zoneId={123456} adType={1234} />
</>
)
}Results! 🎉
With PortraitTracker, KevelProvider, and AdZone all set up, you should now be able to see ads!
You can see test ads by adding the query parameter ?testing=yes to the end of your URL.
Tailwind
Run npx tailwindcss -i ./src/styles/input.css -o ./src/styles/output.css --watch in your terminal to ensure Tailwind is monitoring the correct files when developing or styling components.