Integration guide

Embed the Growl product ads on your app or website

Embedding Growl product ads to your website is a simple process. All you need to do is add a small snippet of code to your website’s HTML and setup ad slots.

Add Growl script

Get your script tag

The script tag is what loads the ads on your site. Here is a template of what it looks like:
```
<script
  src="https://cdn.withgrowl.com/ads.js"
  data-growl-publisher-id="YOUR_PUBLISHER_ID"
></script>
```
Replace YOUR_PUBLISHER_ID with your actual publisher ID.
You can selectively disable ads for a page or user. Learn more in the section on disabling ads.

Advanced: You can optionally route Growl events through your own domain using a CNAME record. This can help with ad blockers and improve event delivery. See Using a Custom Domain for setup instructions.
Find Your Publisher ID

You can find your unique Publisher ID in the Growl Dashboard.
Add the script to your website

Once you have your script tag with your Publisher ID, add it to your website’s HTML file.

The best place to put the script is right before the closing </head> tag of your HTML document. This is done to prevent content layout shifts on ad load since the Growl script loads before your <body> tag.

Here is an example of what your HTML file might look like after adding the script:
```
<!DOCTYPE html>
<html>
  <head>
    <title>My Awesome Website</title>
     <script
      src="https://cdn.withgrowl.com/ads.js"
      data-growl-publisher-id="YOUR_PUBLISHER_ID"
    ></script>
  </head>
  <body>
    <h1>Welcome to my website!</h1>
    <p>Here is my content.</p>

    

  </body>
</html>
```
You can add the optional attribute data-growl-debug to the <script> tag to see Growl debug messages in console. We only recommend this in dev environments.
Verify Your Installation

After adding the script to your website:
1. Save the changes to your HTML file.
2. Upload the updated file to your web server if needed.
3. Open your website in a web browser.
You should now see the Growl ads ads.js load in your browser’s network tab.

Mark ad slots

Growl ads are only placed in marked ad slots. To mark an ad slot:

Use data-growl-slot attribute on the element.
You can optionally add data-growl-slot-name to give the ad slot a name to track it in the Growl dashboard. Note: Remember to use unique name values for the slots you want to track.
Add data-growl-unit attribute and assign the AD_UNIT_ID obtained from Growl dashboard. Learn more about Ad Units here.
Optionally add data-growl-theme ("dark" or "light", defaults to "light"). Learn more in the section on ad theme.

<div class="ad-container">
  <div data-growl-slot
       data-growl-unit="AD_UNIT_ID"><!-- YOUR AD WILL DELIVER HERE --></div>
</div>

<div class="ad-container">
  <div data-growl-slot
       data-growl-slot-name="alex-companion-card"
       data-growl-unit="AD_UNIT_ID"><!-- YOUR AD WILL DELIVER HERE --></div>
</div>

Initialize Growl Ads

By default, Growl automatically attempts to serve ads into marked slots when the page loads. This works well for server-side rendered (SSR) sites where ad slot markup is present during initial page load.

For single-page applications (SPAs) built with frameworks like React, Vue, or Svelte, you must call window.GrowlAds.init() after your ad slots have been rendered to the DOM. This is typically done in a useEffect hook or component lifecycle method.

// React example
useEffect(() => {
  // Your ad slots are now rendered
  window.GrowlAds.init();
}, []);

Provide contextual data

Contextual data is important to serve relevant ads which perform well and increase revenue for you. For Growl product integration ads, you must manually share the data with the Growl Ad engine to serve relevant ads.

For badge ads, you have to manually send contextual data. You can do so by using data-growl-* attributes.

Only the following are currently supported:

data-growl-description: A brief description of the context (OPTIONAL)
data-growl-keyword: A comma separated list of keywords associated with the ad (OPTIONAL)

Ad creative persistence

In some special cases, you need the same ad creative to be shown in multiple ad slots. You can use the data-growl-key attribute to achieve that. Learn more about ad key here.

Ad styling

Each Growl Ad is rendered inside an iframe to keep your page secure. The iframe is placed inside the ad slot specified using the data-growl-slot attribute.

The styling of the ad is decided by the data-growl-unit value. Styling for the ad creative is set in the Growl dashboard. This includes the ad creatives size, color scheme and font among other things. Contact the Growl team to learn more.

Ad theme

Use the optional data-growl-theme attribute on ad slot elements to control the theme. Valid values: "dark" or "light" (default: "light").

<div class="ad-container">
  <div data-growl-slot
       data-growl-slot-name="alex-companion-card"
       data-growl-unit="AD_UNIT_ID"
       data-growl-theme="dark"
  ><!-- YOUR AD WILL DELIVER HERE --></div>
</div>

To change the theme dynamically, you must first update the data-growl-theme attribute on all ad slot elements, then call window.GrowlAds.init():

// should only be called after the theme is changed
function onThemeChange(newTheme) {
  const adSlots = document.querySelectorAll('[data-growl-slot]');
  adSlots.forEach(slot => {
    slot.setAttribute('data-growl-theme', newTheme); // 'dark' or 'light'
  });

  window.GrowlAds.init(); // must be called
}

A/B testing ad theme

Disable ads

You can use an optional data-growl-ads-disabled attribute on the script tag to disable ads. When disabled, Growl will only deliver a pixel for tracking but will not deliver an Ad. This is useful for audience measurement and retention tracking.

<script
  src="https://cdn.withgrowl.com/ads.js"
  data-growl-publisher-id="YOUR_PUBLISHER_ID"
  data-growl-ads-disabled
></script>

That’s it! Your Growl ads are now embedded. If you have any trouble, please contact our support team.