Integrate
Server-side integration
A server can ask for one ad after the model has answered, using only the data this site already lists. The live endpoint and the real field names stay in the verified API reference.
On this page
A server can ask Visor for one ad after the model has answered. The browser, or the app, renders what came back, or it renders nothing. Use this path when the client should not hold a secret, when you want one place that decides what leaves the building, or when a native app draws its own UI.
The request on this page is illustrative. Field names are illustrative. The real request format is in the verified API reference. YOUR_AD_ENDPOINT is not a published URL. Placement still applies: ask after the finished answer, one ad, nothing on an empty result.
When the server should ask
Ask from the server in three cases. A native app, including iOS, Android, React Native, and Flutter, should not embed a secret in the binary. A web app that wants a single choke point for personal data should strip it before the request, not in a browser console. And any app that was issued a value which must stay server-side should keep that value in the server environment.
A website that only has a public snippet can stay on the web snippet page. You do not have to proxy the snippet through your server to be allowed on the network. Proxy it when it helps you keep a secret, or when the client is a native shell. Mobile apps and webviews is the native side of the same choice.
Ask after the model has finished. Do not call from the server on the first token. Do not call for a refusal, an error, or an empty answer. Do not call for an account marked under 18. No ad is requested before approval, and no live publisher ID exists before the traffic check passes.
What a request may include
You may send the current conversation or a short topic summary, anonymized in-app signals, device type, country, an under-18 flag, and a pseudonymous identifier. The privacy policy also describes device type as phone, tablet, or computer, and country on this network as the United States. A pseudonymous identifier is a stand-in the app chooses. It is not a name, an email, or a phone number. Name, email, phone, and street address come off before matching. Topic, intent, length, device, and a US region bucket stay. That kept set is not a second list of fields to send. We do not sell personal data. The SDK sets no cookie.
The sample JSON uses a topic summary, a device type, country US, an under-18 boolean, the publisher ID, and an optional pseudonymous id. Anonymized in-app signals are on the allowed list too. The sample does not include a key for them. Add them only under the name your integration docs use.
If a person types an email or a phone number into the chat, that text is inside the message. Send a topic summary instead of the raw transcript when you can. Visor does not call the model, and it does not need the provider or the provider’s key.
An illustrative request
Both samples post JSON to process.env.YOUR_AD_ENDPOINT in spirit: Node reads that variable, and the Python sample reads the same name from the environment. The body uses only the data listed above. Field names are illustrative. The real request format is in the verified API reference.
// Illustrative.
// Field names are illustrative. The real request format is in the
// verified API reference. YOUR_AD_ENDPOINT is not a published URL.
// YOUR_TIMEOUT_MS is a number you choose. Visor does not publish one.
// The response body is not public. Render nothing if you cannot use the issued format.
type IllustrativeAdRequest = {
publisherId: string;
topic: string;
deviceType: "phone" | "tablet" | "computer";
country: "US";
under18: boolean;
pseudonymousId?: string;
};
export async function requestAd(
input: IllustrativeAdRequest,
): Promise<string | null> {
const endpoint = process.env.YOUR_AD_ENDPOINT;
const timeoutMs = Number(process.env.YOUR_TIMEOUT_MS);
if (!endpoint || !Number.isFinite(timeoutMs) || timeoutMs <= 0) return null;
if (input.under18 || input.country !== "US") return null;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const response = await fetch(endpoint, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(input),
signal: controller.signal,
});
if (!response.ok) return null;
const raw = await response.text();
if (!raw) return null;
return raw;
} catch {
return null;
} finally {
clearTimeout(timer);
}
}The samples return the raw body or null. They do not know the real schema. Do not inject that string into a page as HTML until your integration docs tell you the format. When you cannot render from the issued format, render nothing. Use only keys the issued format names.
The samples also skip the call when the account is under 18 or when the country is not the United States. That guard is yours. It is not a published error payload. How the account is authenticated on the request is part of the API reference. The sample does not include an authorization header.
What you must never send
Matching does not use personal data, and it does not use a third-party cookie. The SDK sets no cookie. Name, email, phone, and street address come off before matching. Leave these out of the JSON, out of headers you add, and out of the URL.
| You may send | Do not send |
|---|---|
| The current conversation, or a short topic summary | Name, email address, or phone number |
| Anonymized in-app signals | Precise location, such as GPS or a street address |
| Device type: phone, tablet, or computer | Payment data, a government ID, or a password |
| Country. On a live request that country is the United States | A third-party cookie |
| An under-18 flag | A device advertising ID |
| A pseudonymous identifier you chose | Browsing history from other websites |
Do not send the device advertising ID. Visor does not ask for it. Do not send your model provider’s key. Do not send a session cookie from another site. The privacy policy is the source for the data boundary. This page does not widen it.
An empty result
Treat a non-OK status, an empty body, a network error, and a timeout as no-fill. Render nothing. The real status codes are in the verified API reference. This page does not list them, so the samples use the conservative rule: if you did not get a body you are able to render from the issued format, show no ad.
Do not keep a house ad in the slot to avoid an empty state. Do not leave the previous answer’s ad in place. Do not reserve a gap. No-fill is a normal result. The thread closes up.
Timeouts
Set your own short timeout. Render nothing when it fires. Visor does not publish a latency number, so the samples read a number you choose. Choose a wait short enough that a slow response does not hold the thread open after the person has moved on. A spinner that outlives the answer is a reserved gap. Take it down on timeout.
No latency number or uptime number is published. Commercial terms live in your agreement. Do not retry in a loop on the same answer. A retry policy is yours to set. If a retry returns an ad, still render at most one. Do not refresh a shown ad to create another view.
Do not cache the ad
An ad belongs to the answer you just finished. Do not store the response and show it again under the next answer. Do not share one response across users. A cache that serves the same ad under a later question breaks the one-ad-per-answer rule. A cache that serves one person’s ad to someone else is a worse bug.
Ask again after the next answer has finished, or render nothing. Do not prefetch an ad during generation and then hold it until the stream ends if that means you might attach it to a refusal. Wait, then ask, then render or clear.
Logging
A log line can record that a request was made, the time, and whether you rendered an ad. That is enough to debug a blank thread. Do not write the conversation into the log. Do not write the pseudonymous identifier next to a name, an email, or a phone number. The point of the stand-in is that it is not those things.
- Do not log the JSON body.
- Do not log precise location, even if it was stripped before the request.
- Do not log a model provider key or any secret from the environment.
- Do not attach the ad creative to a user profile in your database.
- Do not log the raw response next to a person’s contact details.
How long you keep your own logs is your decision. Visor does not publish one retention clock for every record type, because a payment record and a bid log are not the same. The signed agreement states the schedule for that relationship. The privacy policy says the same thing.
Secrets stay on the server
Read the endpoint from the server environment. Do not ship it in a mobile binary, a public repository, or a NEXT_PUBLIC_ variable if the value is a secret. The publisher ID in the browser samples is a different kind of value: it identifies the app on a client integration you were issued. If you are unsure which kind you were given, keep it on the server until the integration docs say otherwise.
Use HTTPS. The privacy policy says traffic to the ad endpoints should be encrypted in transit. Do not disable certificate checks to make a staging box easier. Staging still counts as a place where a conversation can leak.
- Publisher ID
- The id issued after the traffic check. It identifies the app. It is not a person’s id.
- Pseudonymous identifier
- A stand-in the app chooses. It is not a name, an email, or a phone number.
- No-fill
- No ad qualified, or you could not render one. The app renders nothing and does not keep a gap.
- Topic summary
- A short description of the conversation, used instead of the raw transcript when you choose that option.