## Refresh vs Re-render

GPT [requires ad unit path and size to construct an ad slot](https://developers.google.com/doubleclick-gpt/reference#googletag.defineSlot), 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](https://developers.google.com/doubleclick-gpt/reference#googletag.PubAdsService_refresh).

## 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](https://support.google.com/dfp_premium/answer/4574077) as well as minimizing ad requests.
[Interactive Advertising Bureau (IAB)](http://www.iab.com/) 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.

```js
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.

```js
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`](../../src/utils/apiList.js)
and used to create [GPT mock file](../../src/utils/mockGPT.js).
[`apiList.js`](../../src/utils/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](https://developers.google.com/doubleclick-gpt/reference).

## 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](https://github.com/karma-runner/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](https://github.com/mochajs/mocha).

```js
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.
});
```