Appearance
Google Publisher Tag (GPT)
The GPT layer lets you render Google Display Ads directly inside your Ease Live scenes using Google Publisher Tag (GPT). Connect it to your Google Ad Manager ad unit, configure targeting, and the layer handles loading, rendering, and impression tracking automatically.
You can use the GPT layer like any other layer: position it precisely, animate it in and out, and react to ad lifecycle events using triggers.
Adding a GPT layer
- In Studio, open a scene and click the + button in the layer panel.
- Choose GPT from the layer type list.
- Resize and position the layer on the canvas.
- Enter your ad unit path in the Ad unit field in the inspector.
- Select the ad size that matches your ad unit configuration.
Layer settings
These settings are available in the layer inspector when a GPT layer is selected.
Ad configuration
| Setting | Type | Default | Description |
|---|---|---|---|
| Ad unit | String | (empty) | The full ad unit path from Google Ad Manager, e.g. /12345678/my-ad-unit. |
| Ad size | Select | 300×50 | The dimensions of the ad slot. Choose from a list of standard IAB sizes, fluid for a responsive ad, or custom to specify your own dimensions. |
| Resolution | Number | 1 | Only available for custom sizes. A multiplier applied to the ad dimensions — use this to serve a higher-resolution creative. |
Supported standard sizes (top performers highlighted): 728×90, 336×280, 300×250, 300×50, 160×600, 300×600, 320×50, 320×100, 970×250, 970×90, and many more.
Important: Use GPT layers in fixed-size scenes only. If the scene is set to scale, the ad iframe will be scaled as a bitmap, causing pixelation and readability issues. Custom sizes must also match the sizes your ad unit is configured to serve.
Behaviour
| Setting | Type | Default | Description |
|---|---|---|---|
| Auto hide | Boolean | false | Automatically hides the layer when no ad is returned (empty response or error). Useful to prevent showing blank space in your layout. |
| Refresh | Boolean | false | Automatically refreshes the ad after it has been displayed for a set duration. The first refresh happens after the interval elapses from the initial load. |
| Interval | Number (seconds) | 60 | How often to refresh the ad, in seconds. Minimum value is 30 seconds. Only visible when Refresh is enabled. |
Targeting parameters
Add key-value pairs to pass audience or contextual targeting information to Google Ad Manager. Each key can have one or more values — use comma-separated strings for multiple values.
Example:
| Key | Value |
|---|---|
sport | football |
content_type | highlights,live |
Triggers
The GPT layer fires the following triggers, which you can use to drive logic, animations, or other actions in your scene.
Ad lifecycle
| Trigger | When it fires | Properties |
|---|---|---|
| gptRequested | The ad request has been sent to Google Ad Manager. | event (object) — the raw GPT ad service event. |
| gptLoad | The ad has loaded and rendered successfully. | event (object) — the raw GPT ad service event. |
| gptError | The ad failed to load. See Error reporting for details. | event (object) — the raw GPT ad service event. |
| gptImpressionViewable | The ad impression has been counted (the ad was visible on screen for the required duration). | event (object) — the raw GPT ad service event. |
| gptVisibilityChanged | The viewability of the ad slot has changed. | event (object) — the raw GPT ad service event. |
Standard layer triggers
The GPT layer also supports the standard triggers available on all layers:
click, show, hide, resize, pointerEnter, pointerExit, pointerPress, pointerRelease
Error reporting
When an ad fails to load, the GPT layer fires a gptError trigger. The trigger carries an event object with a message field describing what went wrong.
event.message | What it means |
|---|---|
"Received empty response" | Google Ad Manager responded but returned no ad — the slot had no fill. |
"Request timed out" | No response was received within 2 seconds of the ad request being sent. |
"Google Ads API failed to load" | The GPT script could not be loaded. This is usually caused by an ad blocker or a network issue preventing access to securepubads.g.doubleclick.net. |
Auto-hide on error: When the Auto hide setting is enabled and a gptError fires, the layer is hidden automatically — no trigger wiring required.
Example use: Wire gptError to show a fallback image, log the error to a data source, or display a different scene.
Notes
- No GPT-specific actions are available. To control the layer programmatically, use standard layer actions such as Show layer, Hide layer, or Set layer property.
- The GPT layer requires the Google Ads API to be reachable at runtime. In environments where
securepubads.g.doubleclick.netis blocked (e.g. corporate networks, browser ad blockers), ads will not serve and the layer will fire agptError. - Each GPT layer corresponds to a single ad slot. To display multiple ads simultaneously, use multiple GPT layers with different ad unit paths.