# GAM Creative Setup

This page explains the creative template used by Nexx360 line items in Google Ad Manager to render winning bids from n360ortb.

## Overview

When a Nexx360 line item wins in the GAM auction, it renders a creative that:

1. Loads the n360ortb display library
2. Uses GAM macros to identify the winning bid
3. Renders the ad from Nexx360's servers

## Creative Template

The following creative template is used by Nexx360 line items:

```html
<script src="https://lib.nexx360.io/nexx360display/api.js"></script>
<script>
  var ucTagData = {
    bidId: '%%PATTERN:n360_bid%%',
    size: '%%PATTERN:n360_sz%%',
    pubUrl: '%%SITE%%'
  };
  n360ortbDisplay.renderAd(document, ucTagData);
</script>
```

## How It Works

### 1. n360ortbDisplay Library

```html
<script src="https://lib.nexx360.io/nexx360display/api.js"></script>
```

This lightweight library provides the `renderAd()` function that fetches and renders the ad creative.

### 2. GAM Macros

The template uses GAM macros to pass bid information:

| Macro                  | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `%%PATTERN:n360_bid%%` | The unique bid identifier set by `setDisplayBids()` |
| `%%PATTERN:n360_sz%%`  | The ad size (e.g., "300x250")                       |
| `%%SITE%%`             | The page URL where the ad is served                 |

### 3. renderAd() Function

```javascript
n360ortbDisplay.renderAd(document, ucTagData);
```

This function:

* Automatically detects the rendering environment (friendly iframe, SafeFrame, or cross-origin iframe)
* Fetches the ad creative using the bid ID
* Renders the ad into the current document
* Handles iframe resizing so the ad displays at the correct dimensions

{% hint style="success" %}
The same creative template works whether GAM serves the creative in a **friendly iframe** or a **SafeFrame**. The library detects the context at runtime and adapts automatically — no configuration change is needed.
{% endhint %}

### Rendering with SafeFrame

When GAM serves the creative inside a SafeFrame (a cross-origin iframe from `tpc.googlesyndication.com`), the library cannot access the parent page directly. Instead it:

1. Sends a `postMessage` to the parent page to request the ad markup via the bid ID
2. The n360ortb library on the publisher page responds with the ad data
3. The creative renders the ad, then sends an `n360:resizeRequest` message
4. The parent page resizes the SafeFrame iframe and its GAM wrapper div to the correct dimensions

This happens transparently — the creative template is identical whether SafeFrame is enabled or not.

### Rendering without SafeFrame

When GAM serves the creative in a regular (friendly) iframe, the library accesses the parent `n360ortb` API directly to retrieve the ad markup from the bid store. It then resizes the parent iframe via `frameElement` to match the ad dimensions.

## Creative Setup in GAM

{% hint style="info" %}
When you connect your GAM account, Nexx360 automatically creates the line items and creatives. You typically don't need to set these up manually.
{% endhint %}

If you need to verify or manually create the creative:

1. Go to **Delivery** > **Creatives** in GAM
2. Find or create a third-party creative
3. Set the creative type to **Third party**
4. Paste the creative template code
5. Set appropriate sizes (or use a 1x1 fluid creative)

## Debug Mode

To troubleshoot creative rendering issues, add `debug: 1` to the creative config:

```html
<script src="https://lib.nexx360.io/nexx360display/api.js"></script>
<script>
  var ucTagData = {
    bidId: '%%PATTERN:n360_bid%%',
    size: '%%PATTERN:n360_sz%%',
    pubUrl: '%%SITE%%',
    debug: 1
  };
  n360ortbDisplay.renderAd(document, ucTagData);
</script>
```

With debug mode enabled, detailed logs appear in the browser console with module-specific prefixes (e.g., `[n360ortb-display:env]`, `[n360ortb-display:messenger]`). These logs show:

* Environment detection results (direct, SafeFrame, or cross-domain)
* PostMessage communication between creative and parent page
* Iframe creation and resize operations
* Error details if rendering fails

## Troubleshooting

### Ad not rendering

1. **Check targeting**: Verify the n360ortb targeting keys are being set
   * Use browser dev tools to inspect GPT targeting
   * Look for `n360_bid`, `n360_pb`, `n360_sz` keys
2. **Check line item delivery**: In GAM, verify the line item is:
   * Active and within flight dates
   * Not limited by frequency caps
   * Properly targeted
3. **Check creative approval**: Ensure creatives are approved in GAM

### Blank creative

If the creative space appears but shows blank:

1. Check browser console for JavaScript errors
2. Verify the n360ortbDisplay library loaded successfully
3. Confirm the bid ID macro is populated (not empty)

### Wrong size rendered

If the ad renders at an incorrect size:

1. Verify sizes match between GPT slot and n360ortb configuration
2. Check that the `n360_sz` targeting key contains the correct size
3. Ensure the creative in GAM supports the expected sizes

## Advanced: Custom Creative

For advanced use cases, you can customize the creative template. `renderAd()` returns a Promise that resolves to `true` on success:

```html
<script src="https://lib.nexx360.io/nexx360display/api.js"></script>
<script>
  var ucTagData = {
    bidId: '%%PATTERN:n360_bid%%',
    size: '%%PATTERN:n360_sz%%',
    pubUrl: '%%SITE%%'
  };

  n360ortbDisplay.renderAd(document, ucTagData).then(function(success) {
    if (success) {
      console.log('Ad rendered successfully');
    } else {
      console.log('Ad render failed');
      // Show fallback content
    }
  });
</script>
```

You can also render ad markup directly if you already have it:

```html
<script src="https://lib.nexx360.io/nexx360display/api.js"></script>
<script>
  // Render markup with a size string
  n360ortbDisplay.renderMarkup(document, adMarkup, '300x250');

  // Or with explicit dimensions
  n360ortbDisplay.renderMarkupWithSize(document, adMarkup, 300, 250);
</script>
```

{% hint style="info" %}
See the [Display Library API Reference](/integration-methods/direct-integration-n360ortb/display-api-reference.md) for the complete `n360ortbDisplay` API.
{% endhint %}

## Next Steps

* [GAM Integration Example](/integration-methods/direct-integration-n360ortb/gam-integration.md) - Complete integration code
* [Connect your GAM Account](/integration-methods/direct-integration-n360ortb/gam-integration/connect-your-gam-account.md) - Initial setup
* [API Reference](/integration-methods/direct-integration-n360ortb/api-reference.md) - Full API documentation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.nexx360.io/integration-methods/direct-integration-n360ortb/gam-integration/gam-creative-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.