JavaScript SDK

Get started with our general purpose JS SDK built for any browser-based app

To get started, you will need to set up a publisher account to get a publisherToken and code

1. Import the SDK

<script type="module">
  import { fetchAd } from 'https://server.megabrain.co/sdk/js';
</script>

In case fetchAd can’t be accessed in downstream code, you might need to make fetchAd available globally.

<script type="module">
  import { fetchAd } from 'https://server.megabrain.co/sdk/js';
  window.fetchAd = fetchAd
</script>

2. Assemble messages & set up params

Prepare a list of messages exchanged between the assistant and the user. These messages help determine the most relevant ad to display. The order matters—messages should be listed chronologically and must end with the assistant’s latest reply.

const messages = [
  {
    id: "message-uuid", // a unique identifier for the message, can be a UUID or any unique string
    createdAt: "2024-12-31T12:00:00.000Z", // date formatted as ISO 8601 string
    role: "user", // "user" | "assistant"
    content: "I am looking for a frying pan."
  },
  {
    id: "message-uuid2",
    createdAt: "2024-12-31T12:00:06.000Z",
    role: "assistant",
    content: "For a versatile frying pan, consider an all-clad stainless steel or non-stick hard-anodized aluminum pan, 10–12 inches in size, depending on your needs."
  }
]

If you’re integrating Kontext into a human-to-human messaging app, assign the “assistant” role to all participants except the current user. This approach works reliably in both 1:1 and group chat scenarios.

Create your params object

Use this object to call the fetchAd function. The parameters help the ad server decide which product and ad copy to return based on the context of the conversation.

const fetchAdParams = {
    // a string received during the account setup
    publisherToken: "example-token",
    // a string received during the account setup
    code: "example-code",
    // a persistent user identifier - a unique ID such as uuid or user email hash is recommended
    userId: "user-uuid",
    // a unique ID of this particular conversation - a unique ID such as uuid is recommended
    conversationId: "conversation",
    // a local logging level: "debug" | "info" | "log" | "warn" | "error" | "silent"; a more verbose log level will help you debug issues during development
    logLevel: "silent",
    // a list of messages between assistant and user, as defined above
    messages: messages,
    // a HTML node we'll insert the ad into; this element must be present in the DOM when you call `fetchAd`
    element: document.getElementById("ad-container")
 }

3. Show your first ad

To understand how the ad request works, check out our fetchAd docs.

At this point, you are all set. You can now call the fetchAd function which accepts optional callbacks to support debugging, analytics tracking, or custom rendering logic at various stages of the ad lifecycle.

fetchAd(fetchAdParams, {
  onStart: () => {/* called just before the ad server request */ },
  onComplete: (content, metadata) => {/* called when ad is placed on the page */},
  onError: (error: any) => {/* called when ad streaming encounters an error */},
  onBid: (value: number | null) => Promise<boolean> {/* called when an ad is available to fill your ad slot along with the bid value for the ad. Return true if you want to render the ad. */}
  onAdClick: (impression: { id: string, content: string }) => {/* called when ad is clicked on (for your analytics) */},
  onAdView: (impression: { id: string, content: string }) => {/* called when ad is viewed (for your analytics) */},
})

Assistant

Responses are generated using AI and may contain mistakes.