Help
Troubleshooting
Most empty slots are a no-fill, a request that went out too early, or a traffic check that has not passed. This page maps each symptom to a cause and a fix.
On this page
Work from the symptom to the cause, then change one thing. Most empty slots are a no-fill, a request that went out before the answer existed, or a traffic check that has not passed. A no-fill is a normal result. The thread should close up.
Samples below are illustrative. YOUR_TIMEOUT_MS is a placeholder. askAfterAnswer is your function, not a Visor method.
Symptom table
| Symptom | Likely cause | What to change |
|---|---|---|
| No ad | Check still open, country is not the US, under-18 flag, broad blocks, early request, or a true no-fill | See No ad shows. Render nothing when nothing qualifies. |
| A blank gap | The page reserved a height for a unit that never came | Remove the box. Render nothing. |
| Ad inside the answer, or between messages | The slot is in the message list, or it shares a node with the stream | One slot after the finished answer. See Wrong place. |
| Label missing, or the wording changed | CSS or a rewrite hid or replaced Ad · Sponsored | Keep the words, plain, at the top-left. See Label. |
| Layout shift | A reserved hole, or the ad inserted above the answer | Do not hold a gap. See Layout shift. |
| Snippet never loads | Content-Security-Policy blocked the issued host | Allow that host only. See CSP. |
| Request hangs | Your wait has no end | Set your own timeout. Then render nothing. See Timeout. |
| Two ads, or two requests | Two calls for one answer, or a React effect that runs twice in development | One request per answer. See Duplicates. |
| Click replaces the chat | The webview loaded the landing page in place | Open the https link outside the chat. See Webview. |
| Counts disagree | Your log counts requests and renders. The report counts views | Expect the records to differ. See Reporting. |
| ads.txt warning | The file is missing, or the line was guessed | Use the issued line. See ads.txt. |
| Locked docs will not open | Sign-in is not connected, or review has not passed | See Locked pages. |
No ad shows
An empty thread is not, by itself, a broken integration. Visor returns one ad or it returns nothing. Separate the cases below before you write to Support.
The traffic check has not passed
Ads stay off until the traffic check passes. The signup form does not issue a publisher ID or a snippet. Both arrive with the publisher agreement. No approval time is published. Sign-in is not connected yet.
The traffic is not in the United States
Country on a live request means the United States. Any other session gets no ad. There is no second product for that traffic, and a non-US session is the wrong test of a live slot. How it works states the same limit.
The under-18 flag is set
An account marked under 18 does not get an ad. That result is correct. If every test account is flagged, every test looks empty. Apps directed at children under 13 are not a fit. The ad content policy is the source, and Controls and brand safety covers the switch.
Category blocks are too broad
Some categories never run. That list is fixed. On top of it, a publisher can block alcohol, dating, health products, loans and other credit offers, and specific advertisers, and any brand or domain they name. A long block list can leave nothing eligible, which is a no-fill. Render nothing. Narrow the extra blocks if you wanted a chance of an ad. You cannot loosen the ad content policy.
The request went out before the stream finished
A request sent while the model is still writing can return nothing, or it can sit in a bubble that is still growing. Wait until the stream has finished, then ask once. Do not ask on each token. Placement is the rule.
No ad qualified
Buyers bid, and an in-house classifier picks from anonymized context. If nothing qualifies, nothing is returned. Render nothing: no blank box, no skeleton, no house ad, no refresh loop, and no error in the thread. We do not publish a fill rate.
A gap, or the page moves
A blank gap appears
An empty rectangle under the answer usually means you reserved a height: a minimum height, a skeleton, or a placeholder you render before the response arrives. When Visor returns nothing, that box is still there. Empty the node and remove it from layout. The thread should look as if you never asked. The publisher guidelines say the same thing.
// Illustrative. Your page, not a Visor callback.
// If there is no ad, empty the slot and take it out of the layout.
function renderNothing(slot) {
slot.replaceChildren();
slot.hidden = true;
}The layout shifts
The answer jumps when an empty slot has a height, or when the ad is inserted above the answer. Paint the finished answer first. Put the slot after it, with no minimum height while empty. Content under the slot can move when an ad arrives. That is the ad arriving last. You do not design the card or the strip. We do not publish a layout-shift score. See UX guidelines.
The ad is in the wrong place
The ad shows inside or between messages
The unit is in the answer, between the question and the answer, or in a bubble that reads like the assistant. The slot was rendered as a message, or the stream writes into the same node, so later tokens wrap the ad. Finish the answer in one element. Render one slot as the next sibling, once. Do not style it as the assistant’s turn. Ad formats describes the card and the strip. Both stay outside the model’s words.
The label
The label is missing or restyled
The words Ad · Sponsored are gone, shortened, or styled to match the assistant. The label is always those two words, with a middle dot, in plain text, at the top-left. The wording does not change.
- Do not set the label to
display: none, a zero font size, or a color that matches the background. - Do not replace the words with “Sponsored” alone, “Promoted”, or a logo.
- Do not restyle the label so it reads as the assistant’s name.
- Check thread-wide CSS for
button,a, and small text. A broad rule can catch the label.
This page does not publish the markup classes inside the unit. Do not guess a class and hide it. The ad content policy forbids an ad that imitates the assistant.
The snippet or the request fails
Content-Security-Policy blocks the snippet
The browser console says a script or a connection was blocked by Content-Security-Policy. That is the page’s policy, not a no-fill. The console names the directive and the host. Allow the host on the snippet you were issued, and no other. Do not copy a host from this page. None is published. Do not allow every host. After the change, confirm you still render nothing when there is no ad.
The ad request times out
Visor does not publish a timeout or an error code for a slow response. You set the wait in your app. Clear it if a response arrives first. If the timer wins, render nothing, the same as a no-fill. Do not show an error in the thread, and do not send a second request from the timer. The number in the sample is a placeholder, not a Visor limit.
// Illustrative. YOUR_TIMEOUT_MS is a number you choose.
// Visor does not publish a timeout on this page.
// askAfterAnswer is your function, not a Visor method.
function askWithTimeout(slot) {
const timer = setTimeout(() => {
slot.replaceChildren();
slot.hidden = true;
}, YOUR_TIMEOUT_MS);
askAfterAnswer().then((ad) => {
clearTimeout(timer);
if (!ad) {
slot.replaceChildren();
slot.hidden = true;
return;
}
slot.hidden = false;
});
}Two ads, or the same request twice
The app asks twice for one answer
Two units, or two network calls, usually mean the slot is mounted twice, the stream handler and an effect both ask, a retry does not cancel the first request, or the answer id changes on every token. Use a stable id for the finished answer. Ask from one place. Publisher terms say you do not refresh the slot in a loop.
React Strict Mode runs the effect twice in development
In development, React Strict Mode runs the effect, cleans it up, and runs it again. Production does not do this. Ignore the cancelled run. Clear the ref in the cleanup so the second run can ask once. A ref that never resets skips that remount, and development shows no request. Do not turn Strict Mode off and ship two slots. @visor/react on React and Next.js is an illustrative sample, not an install command.
import { useEffect, useRef, useState } from "react";
// Illustrative. Not a Visor API and not a published package.
// askAfterAnswer is your function. The publisher ID comes after the check.
declare function askAfterAnswer(answerId: string): Promise<string | null>;
export function useOneAsk(answerId: string, streamDone: boolean) {
const asked = useRef<string | null>(null);
const [, setAd] = useState<string | null>(null);
useEffect(() => {
if (!streamDone) return;
if (asked.current === answerId) return;
asked.current = answerId;
let ignore = false;
askAfterAnswer(answerId).then((ad) => {
if (!ignore) setAd(ad ?? null);
});
return () => {
ignore = true;
// Strict Mode runs cleanup, then the effect again, in development.
// Clear the guard so that second run can ask once.
if (asked.current === answerId) asked.current = null;
};
}, [answerId, streamDone]);
return null;
}askAfterAnswer is your function, not a published endpoint. The JavaScript path is the same rule without Strict Mode: one id, one call.
The click stays in the webview
The click opens inside the webview
In an iOS or Android webview, the ad link often loads in place and replaces the chat. That is the webview, not a second placement. Open https clicks in the system browser. This page does not name a Visor callback for that handoff. The locked SDK page is for approved accounts. Mobile states the public rule.
Counts and ads.txt
The numbers do not match your logs
Expect your log and the report to differ. Reporting counts ad views, clicks, and US dollars. A view and an impression are the same count: an ad that was shown, under the rule in the publisher agreement. A request, a no-fill, a timeout, a blocked request, and an ad you did not render are not views. Invalid traffic is filtered out of the counts pay uses. Pay is a CPM on views, not pay-per-click. The report time zone, a network eCPM, a fill rate, and a reconciliation formula are not published. Payments says where the money terms live.
ads.txt warnings
For a site, buyers read /ads.txt at the root domain. For an app, post app-ads.txt on the developer website listed in the store, not inside the binary. ads.txt and sellers.json is the full page. Visor’s sellers.json is not published, and you do not host it. Your Visor line is issued after the traffic check, with the publisher agreement. Do not guess a domain, a seller id, or DIRECT versus RESELLER. The ad-request publisher ID is not automatically that seller id. Copy the issued line unchanged, and omit a certification-authority id unless the line includes one.
Locked docs will not open
A locked page stays closed
SDK, API, Matching, OpenRTB, and Webhooks stay locked until review. The body is not sent to the browser. Sign-in is not connected, and it does not check a password, so the pages stay closed for everyone. That is not an outage. There is no status page. Quickstart and Placement stay public.
If it is still stuck
Write through Contact on the Publishers lane. Include the app name, the publisher ID if one has been issued, the page URL, the steps, the time with the time zone, and the browser or device. Add a screenshot of the slot. Do not include a user’s name, email, phone number, precise location, payment data, or government ID. Say which row of the table you already ruled out. Support lists the same boundary.