VTEX Ads Core Package Examples

Practical examples demonstrating how to fetch sponsored product placements for search results, category pages, and homepage.

These examples demonstrate how to use the getRawAds function to fetch sponsored product placements based on different contexts in your storefront. Each use case shows how to build a request for the ad server using the user's identity and relevant search or category criteria, and then extract the returned sponsored products.

You can adapt these patterns to power your search results, category pages, homepage, and more — customizing placements, targeting, and quantity as needed.

Simple product search

This example fetches ads for a search term, such as "smartphone", and retrieves sponsored products at the top of the search results.


_32import { getRawAds } from "@vtex/ads-core";
_32
_32async function getSearchAds(searchTerm, userId, sessionId) {
_32  const adRequest = {
_32    identity: {
_32      accountName: "mystore",
_32      publisherId: "pub-123",
_32      userId,
_32      sessionId,
_32    },
_32    search: {
_32      term: searchTerm,
_32    },
_32    placements: {
_32      search_top_product: {
_32        quantity: 4,
_32        types: ["product"],
_32      },
_32    },
_32  };
_32
_32  try {
_32    const ads = await getRawAds(adRequest);
_32    return ads.sponsoredProducts.search_top_product || [];
_32  } catch (error) {
_32    console.error("Failed to fetch search ads:", error);
_32    return [];
_32  }
_32}
_32
_32// Usage
_32const searchAds = await getSearchAds("smartphone", "user-123", "session-456");

Category page ads

This example will fetch ads for a specific category, such as "electronics", for two placements: category_top_product, which represents sponsored products at the top of the results, and category_shelf, which is an additional shelf included on the category page.


_29async function getCategoryAds(categoryId, userId, sessionId) {
_29  const adRequest = {
_29    identity: {
_29      accountName: "mystore",
_29      publisherId: "pub-123",
_29      userId,
_29      sessionId,
_29    },
_29    search: {
_29      selectedFacets: [{ key: "category", value: categoryId }],
_29    },
_29    placements: {
_29      category_top_product: {
_29        quantity: 3,
_29        types: ["product"],
_29      },
_29      category_shelf: {
_29        quantity: 8,
_29        types: ["product"],
_29      },
_29    },
_29  };
_29
_29  const ads = await getRawAds(adRequest);
_29  return {
_29    topAds: ads.sponsoredProducts.category_top_product || [],
_29    shelfAds: ads.sponsoredProducts.category_shelf || [],
_29  };
_29}

Home page ads

This will fetch ads for the homepage, including a top product placement and a shelf of products. This is useful for displaying featured products or promotions on the main page of your store.


_27async function getHomepageAds(userId, sessionId) {
_27  const adRequest = {
_27    identity: {
_27      accountName: "mystore",
_27      publisherId: "pub-123",
_27      userId,
_27      sessionId,
_27    },
_27    search: {}, // No specific search criteria
_27    placements: {
_27      home_top_product: {
_27        quantity: 4,
_27        types: ["product"],
_27      },
_27      home_shelf_product: {
_27        quantity: 12,
_27        types: ["product"],
_27      },
_27    },
_27  };
_27
_27  const ads = await getRawAds(adRequest);
_27  return {
_27    topProducts: ads.sponsoredProducts.home_top_product || [],
_27    shelfProducts: ads.sponsoredProducts.home_shelf_product || [],
_27  };
_27}