Iframe debugging

Use an iframe for interactive web content: a real page, form, canvas experience, or custom interface. Do not use displayHtml() for that job.

An iframe can send a task transition to Portals, and Portals can send text to active iframes through the Send Message To Iframes effect.

Quick checklist

The iframe URL is HTTPS and can be embedded.
The page is opened from an Iframe effect in a real Portals space.
The Portals SDK is loaded before SDK calls.
Messages to Portals are JSON strings, not raw JavaScript objects.
Task names and transition names match exactly.
Any Delay value is a whole number of seconds.

Test the smallest message first

From an action in your iframe, send one task transition:

PortalsSdk.sendMessageToUnity(JSON.stringify({
  TaskName: 'OpenGallery',
  TaskTargetState: 'SetActiveToCompleted',
  Delay: 0
}));

The bridge expects these exact fields:

Field	Required	Description
TaskName	Yes	The exact target task name.
TaskTargetState	Yes	A supported task transition string.
Delay	No	Whole seconds before the transition; use 0 for immediate.

Supported task transition strings

Transition	Use it when
ToNotActive	Reset a task to Not Active.
SetNotActiveToActive	Start a task only when it is Not Active.
SetActiveToCompleted	Complete a task only when it is Active.
SetCompletedToActive	Reactivate a completed task.
SetAnyToCompleted	Complete a task from any current state.
SetAnyToActive	Make a task Active from any current state.
SetActiveToNotActive	Reset an Active task.
SetCompletedToNotActive	Reset a Completed task.
SetNotActiveToCompleted	Complete a Not Active task.

Start with SetActiveToCompleted when that matches your game flow. It provides a clear, intentional transition.

JSON mistake: raw object instead of text

This is not valid because Portals receives a string:

PortalsSdk.sendMessageToUnity({
  TaskName: 'OpenGallery',
  TaskTargetState: 'SetActiveToCompleted'
});

Use JSON.stringify():

PortalsSdk.sendMessageToUnity(JSON.stringify({
  TaskName: 'OpenGallery',
  TaskTargetState: 'SetActiveToCompleted',
  Delay: 0
}));

The iframe does not appear

Confirm the Iframe effect actually runs from its task or trigger.
Open the target URL in a normal browser to confirm the page itself loads.
Confirm the URL uses HTTPS and allows embedding.
Use a simple public page before testing a complex app.
Test the task inside Portals. A normal browser can verify the web page but not the Portals bridge.

A task does not change

Check these in order:

TaskName matches the task exactly, including case and spaces.
TaskTargetState matches a value in the table above.
The task is currently in a state that permits the selected transition.
The JSON text is produced from a user action where the webview requires one.
The page is inside Portals when you test the bridge.

Receive a message from Portals

The no-code Send Message To Iframes effect sends text to active iframes. Keep the format agreed and simple. If you send JSON text, parse it defensively in the iframe:

PortalsSdk.setMessageListener((message) => {
  try {
    const data = JSON.parse(message);
    document.getElementById('status').textContent = data.message;
  } catch {
    document.getElementById('status').textContent = String(message);
  }
});

Set the Portals effect message to one predictable shape, such as:

{"message":"Round started"}

The no-code effect can substitute named values using its supported pipe placeholders. Keep the resulting text valid JSON if your iframe expects JSON.

Closing an iframe

Call the SDK close method from a user action in the iframe:

document.getElementById('close').addEventListener('click', () => {
  PortalsSdk.closeIframe();
});

Do not depend on an automatic close from page load or a background timer. Test it in Portals because webview gesture rules differ from a normal browser.

Keep iframe and Portals responsibilities separate

Put interaction, form behavior, and browser-side UI in the iframe.
Put task transitions, no-code effects, and shared game rules in Portals.
Do not expose private data in iframe URLs or messages.
Use displayHtml only for static overlays.

If messages still fail after the smallest test, make a temporary task with one known transition and verify that before debugging the rest of the page.

Help & Reference