Guides.md

Refresh vs Re-render

GPT requires ad unit path and size to construct an ad slot, for that reason, when adUnitPath or slotSize props change, React GPT destroys an old ad slot and creates a new one which results in rendering a new ad. Additionally, when outOfPage or content props change, React GPT re-renders an ad to create a new ad slot to reflect these props. Any other ad slot related props are reflected by refreshing an ad.

Per instance update vs per page update

When Bling.syncCorrelator([true]) is called before rendering any ad, React GPT triggers ad re-render/refresh to all the ad instances in the page to ensure they use the same correlator value.

Tweaking the render performance

By default, to determine whether the ad should refresh, re-render or should not render, React GPT uses deep equality check against the props in question. You can override this default logic by overriding propsEqual config with your preferred equality check such as shallow equality when you make sure to pass a new object whenever the data changes. To set or override the configuration, call Bling.configure(config).

Viewability

React GPT by default lazy loads an ad when it becomes within the viewport area for viewability as well as minimizing ad requests. Interactive Advertising Bureau (IAB) defines a viewable impression for most of the display ad to be 50% of the ad’s pixels are visible in the browser window for a continuous 1 second. For that reason, React GPT sets the default viewable threshold to be 50% of the ad area. You can however customize this threshold globally or per ad.

import {Bling as GPT} from "react-gpt";

// sets the threashold globally.
GPT.configure({viewableThreshold: 0.3});

class Application extends React.Component {
    // sets the threshold per ad.
    render() {
        return (
            <GPT
                adUnitPath="/4595/nfl.test.open"
                slotSize={[728, 90]}
                viewableThreshold={0.6}
            />
        );
    }
}

You can additionally turn off lazy loading by setting renderWhenViewable to false either globally or per ad.

import {Bling as GPT} from "react-gpt";

// sets the lazy load globally.
GPT.configure({renderWhenViewable: false});

class Application extends React.Component {
    // sets the lazy load per ad.
    render() {
        return (
            <GPT
                adUnitPath="/4595/nfl.test.open"
                slotSize={[728, 90]}
                renderWhenViewable={true}
            />
        );
    }
}

How to keep the module and gpt.js in sync

gpt.js is not in the public VCS and only the latest version is available to load from the public URL. Because of it, we assume gpt.js is almost always backward compatible unless announced in a timely manner by Google.

The current API list is stored in apiList.js and used to create GPT mock file. apiList.js is auto-generated by running update-apilist npm script where it extracts the public API from gpt.js. The mock file is used for unit test and potentially catches the breaking changes on their end although it's less likely to happen.

There are often cases where undocumented APIs are added to the gpt.js, but we will not support those unless it's officially documented.

Test Mode

GPT ad uses iframe to render an ad most of the times and it often fails to render ads within the unit test which itself uses iframe in some unit test libraries such as karma. React GPT offers the test mode where it uses the mock GPT instead of requesting gpt.js.

Here is an example of how to use the test mode in your unit test using mocha.

import {Bling as GPT} from "react-gpt";

describe("My module", () => {
    beforeEach(() => {
        // create a fresh ad manager with test mode for every test.
        GPT.createTestManager();
    });

    // your test goes here.
});