API reference

Detailed description of the Javascript SDK

fetchAd()

Fetches and renders an ad based on the provided parameters and callbacks.

fetchAd(fetchAdParams, callbacks)

Parameters

fetchAdParams · object · required

Configuration options for fetching ads

Show Properties

publisherToken · string · required

Token provided during onboarding

code · string · required

Placement code provided during onboarding

userId · string · required

Persistent user identifier (UUID, hashed email, etc.)

conversationId · string · required

Identifier for the current conversation

logLevel · string

Log verbosity level: “debug” | “info” | “log” | “warn” | “error” | “silent” Default: “silent”

messages · Array<Message> · required

List of conversation messages.

element · HTMLElement · required

DOM element where the ad will be rendered.

callbacks · object

Optional event handlers for the ad fetching process

Show Available Callbacks

onStart · function

Called before the server request starts

onStart: function onStart() {
  console.log("Fetching ad started...");
  showLoadingSpinner();
}

onComplete · function

Called when ad content is fully fetched

onComplete: function onComplete(content, metadata) {
  console.log("Ad fetching complete", content, metadata);
  hideLoadingSpinner();
  renderAd(content);
}

onToken · function

Called after each token is streamed

onToken: function onToken(token) {
  console.log("Received token:", token);
  appendToAdContainer(token); // Dynamically render the content
}

onError · function

Called when streaming encounters an error

onError: function onError(error) {
  console.error("Error while fetching ad:", error);
  showErrorMessage("An error occurred. Please try again later.");
}

onAdClick · function

Called when user clicks the ad

onAdClick: function onAdClick({ id, content }) {
  console.log("Ad clicked:", id, content);
  trackClickEvent(id, content);
}

onAdView · function

Called when ad enters viewport

onAdView: function onAdView({ id, content }) {
  console.log("Ad viewed:", id, content);
  trackViewEvent(id);
}

onBid · function

Called with value which represents the bid amount (in $ CPM) for showing an ad in the ad slot. If value is null, this means we don’t have an ad matching your conversation or we could not submit a bid (possible reasons are that you are outside of contracted geography or you are over the rate limit for your token).

Return true if you want to render the ad or false if you want to skip filling the ad slot with an ad.

onBid: function onBid(value) {
  console.log("Ad can be filled with value:", value);
  return true; // Return true if you want to render the ad. You can also return a Promise<boolean>
}

markAdAsViewed()

Marks an ad as viewed when it becomes visible in the viewport.

markAdAsViewed(impressionId, serverUrl?)

Parameters

impressionId · string · required

The ID of the impression to be marked as viewed

serverUrl · string

The server URL. Defaults to “https://server.megabrain.co”

Messages object

The Message object represents a single message in the conversation context. Each message must have:

id · string · required

Unique identifier for the message

createdAt · string | Date · required

Timestamp when message was created (ISO 8601 string or Date object)

role · string · required

Who sent the message: “user” | “assistant”

content · string · required

The text content of the message

Example message array

const messages = [
  {
    id: "message-uuid-1",
    createdAt: "2024-12-31T12:00:00.000Z",
    role: "user",
    content: "I am looking for a frying pan."
  },
  {
    id: "message-uuid-2",
    createdAt: "2024-12-31T12:00:05.000Z",
    role: "assistant",
    content: "For a versatile frying pan, consider an all-clad stainless steel..."
  }
];

Error handling

The SDK provides robust error handling with:

• Request timeout after 16 seconds by default
• Automatic retry up to 3 times for retriable errors
• Unretriable errors include HTTP 403, 429, and 404

Example error handling:

fetchAd(fetchAdParams, {
  onError: (error) => console.error("Ad fetch failed:", error)
});

Best practices

1. Chronological Order: Ensure messages are listed in chronological order
2. Context Completeness: Include sufficient prior messages for context
3. Unique IDs: Use unique, immutable identifiers for each message

Assistant

Responses are generated using AI and may contain mistakes.