Agent Integration

Overview

Use a single script tag to agent Playgent anywhere. The script injects the iframe for you and automatically triggers the game flow using a handshake to ensure reliability.

Quick start

<script src="https://player.playgent.com/agent.js?key=AGENT_KEY"></script>

• Replace AGENT_KEY with the key provided by Playgent.
• The script creates an iframe after the <script> tag and posts the PG_EMBED_INIT message to the iframe on load (with retries until acknowledged).

How it works

• The loader injects an iframe with src=/embeds/AGENT_KEY on your Player host.
• On iframe load, it sends PG_EMBED_INIT with:
  • url: The page URL by default (you can override)
  • unique: A deterministic, URL-based ID (URL-safe Base64; legacy fallback to a 32-bit hash)
• The loader retries until it receives PG_EMBED_ACK from the iframe.

Sizing and responsiveness

By default the iframe is 100% width and auto-computed height.

• If h and ar are not provided, the loader picks an aspect ratio based on device orientation:
  • Landscape → 16:9
  • Portrait → 9:16
• Height automatically updates with container width changes (ResizeObserver with window-resize fallback).
• Defaults: width 100%, height computed (fallback 600px if needed).

Sizing parameters

• ar or aspect: Aspect ratio (e.g., 16:9, 9:16, 4:3).
• h or height: Fixed height (in px). If present, it overrides computed height.
• maxw or maxwidth: Max width in px (applied as CSS max-width).
• maxh or maxheight: Max height in px (applied as CSS max-height and caps computed height).

Examples:

<script src="https://player.playgent.com/agent.js?key=AGENT_KEY&ar=16:9"></script>
<script src="https://player.playgent.com/agent.js?key=AGENT_KEY&h=640"></script>
<script src="https://player.playgent.com/agent.js?key=AGENT_KEY&ar=9:16&maxw=420&maxh=800"></script>

Border, radius, and shadow (optional)

You can enable a subtle frame around the agent:

• bc or bordercolor: Hex color without # (e.g., f2f3f3).
• bw or borderwidth: Border width in px (default: 1).
• br or borderradius: Corner radius in px (default: 12).
• sh or shadow: on|off (default: on when border is enabled).

Example:

<script src="https://player.playgent.com/agent.js?key=AGENT_KEY&ar=16:9&bc=f2f3f3&bw=2&br=16&sh=on"></script>

URL and unique ID

• url (optional): Override the page URL sent to the agent (e.g., if you want to analyze a canonical URL).
• unique is auto-derived from the exact URL (including query and hash) so repeated loads of the same content map to the same game. No external libraries are used.

Example overriding the page URL:

<script src="https://player.playgent.com/agent.js?key=AGENT_KEY&url=https%3A%2F%2Fexample.com%2Farticle%2F123"></script>

Multiple agents per page

You can include the script multiple times (each instance injects its own iframe). The loader scopes the behavior to the specific <script> tag it follows.

<div>
  <script src="https://player.playgent.com/agent.js?key=KEY_A&ar=16:9"></script>
</div>
<div>
  <script src="https://player.playgent.com/agent.js?key=KEY_B&ar=9:16"></script>
</div>

Mobile apps and webviews

The loader avoids assumptions about desktop-only features and works in common iOS/Android webviews. For constrained environments, ensure the Player host is allowed by your CSP/network policy.

SEO and performance

• The script adds an iframe only and does not modify page content, so it should not affect SEO.
• You can place the script where you want the agent to appear in your layout.
• Optionally defer injection by placing the script below the fold or using your own lazy-loading strategy.

Troubleshooting

• Nothing loads:
  • Verify AGENT_KEY and the Player host domain.
  • Check ad blockers / content filters or CSP rules that may block the Player host.
• Not sized as expected:
  • If using ar, make sure no parent container enforces a conflicting height.
  • Use maxw/maxh to clamp extremes in responsive layouts.
• Unique ID collisions:
  • Unique is derived from the exact URL string. Different query params or order will create a different ID.

Minimal example

<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Playgent agent</title>
  </head>
  <body>
    <h1>Article Title</h1>
    <p>...</p>

    <script src="https://player.playgent.com/agent.js?key=AGENT_KEY&ar=16:9&bc=f2f3f3&bw=2&br=12&sh=on"></script>

    <p>...</p>
  </body>
</html>