VTEX Ads Core Package Basic Usage

Learn the fundamental patterns and APIs for using the @vtex/ads-core package effectively.

Learn the fundamental patterns and APIs for using the @vtex/ads-core package effectively. This section walks you through how to build ad requests and choose between raw or hydrated ad responses, depending on your use case.

Building an ad request

To fetch ads, you first need to construct a request that identifies the user and describes the search context. This request includes:

An identity block: who is making the request (account, user, session).
A search block: the search term, selected facets, or SKU.
A list of placements: where you want ads to appear in your UI.

Identity

The identity tells the ad server who the user is and what session they're in. It also optionally includes the channel (like 'web' or 'mobile'), which helps with targeting and analytics.


_10const identity = {
_10  accountName: "your-account-name",
_10  publisherId: "your-publisher-id",
_10  userId: "user-123",
_10  sessionId: "session-456",
_10  channel: "web", // Optional
_10};

Ad request

Here's how to combine the identity with a search context and ad placements:


_21const adRequest = {
_21  identity,
_21  search: {
_21    term: "smartphone",
_21    selectedFacets: [
_21      { key: "brand", value: "Acme" },
_21      { key: "category", value: "Tools" },
_21    ],
_21    skuId: "SKU-123",
_21  },
_21  placements: {
_21    search_top_product: {
_21      quantity: 3,
_21      types: ["product"],
_21    },
_21    home_shelf_product: {
_21      quantity: 6,
_21      types: ["product"],
_21    },
_21  },
_21};

Fetching raw or hydrated ads

You can choose to fetch either raw ads or hydrated ads, depending on your needs:

Raw ads: lightweight, fast, and ideal if you already have access to product data.
Hydrated ads: include full product info, ready to render.

Using raw ads

Use getRawAds when you want just the ad metadata and plan to enrich it later:


_10import { getRawAds } from "@vtex/ads-core";
_10
_10const rawAds = await getRawAds(adRequest);
_10console.log(rawAds.sponsoredProducts.search_top_product);

When to use:

You already cache product data
You want to implement custom hydration

Using hydrated ads

Use getHydratedAdsFromIS (or a custom hydration strategy) to fetch ads that include full product details:


_10import { getHydratedAdsFromIS } from "@vtex/ads-core";
_10
_10const hydratedAds = await getHydratedAdsFromIS(adRequest);
_10console.log(hydratedAds.sponsoredProducts.byPlacement.search_top_product);

When to use:

You want to skip writing a custom fetcher/matcher
You need full product details out-of-the-box

To implement your own fetcher and matcher for hydration, see the VTEX Ads Core Package Custom Hydration.

Handling partial hydration failures

Hydration may fail for some ads — for example, if the product is no longer in stock. You can inspect and gracefully handle these cases:


_13import { getHydratedAds } from "@vtex/ads-core";
_13
_13const hydratedAds = await getHydratedAds(adRequest, fetcher, matcher);
_13
_13if (hydratedAds.sponsoredProducts.failed.length > 0) {
_13  console.warn(
_13    "Some ads failed to hydrate:",
_13    hydratedAds.sponsoredProducts.failed,
_13  );
_13
_13  const successful = hydratedAds.sponsoredProducts.byPlacement;
_13  // Use fallback logic or continue with successful ads
_13}