Skip to main content

@vtex/ads-core

Core JavaScript SDK for requesting and managing VTEX Ads in any JavaScript environment. This package provides the fundamental advertising functionality with maximum flexibility and control, making it perfect for non-React applications or when you need custom integration patterns.

Installation​

npm install @vtex/ads-core
# or
yarn add @vtex/ads-core

Basic Usage​

Getting Raw Ads​

The simplest way to fetch ads is using getRawAds():

import { getRawAds } from "@vtex/ads-core";

const adRequest = {
identity: {
accountName: "your-account-name",
publisherId: "your-publisher-id",
userId: "user-123",
sessionId: "session-456",
channel: "web", // optional: 'web' | 'mobile'
},
search: {
term: "smartphone", // optional search term
selectedFacets: [
// optional filters
{ key: "brand", value: "Acme" },
{ key: "category", value: "Tools" },
],
},
placements: {
search_top_product: {
quantity: 3,
types: ["product"],
},
},
};

try {
const rawAds = await getRawAds(adRequest);
console.log("Raw ads:", rawAds.sponsoredProducts);
} catch (error) {
console.error("Failed to fetch ads:", error);
}

Getting Hydrated Ads​

For a quick setup using VTEX's Intelligent Search, use the built-in hydration strategy:

import { getHydratedAdsByIS } from "@vtex/ads-core";

const hydratedAds = await getHydratedAdsByIS(adRequest);
console.log("Hydrated ads:", hydratedAds.sponsoredProducts);

Custom hydration​

For ads enriched with product details, use getHydratedAds() with custom fetcher and matcher functions:

import { getHydratedAds } from "@vtex/ads-core";

const customFetcher = async (offers, identity) => {
// Your custom logic to fetch product details
// Return array of products matching the offers
};

const customMatcher = (product, offer) => {
// Your custom logic to match products with offers
// Return true if product matches the offer
};

const hydratedAds = await getHydratedAds(
adRequest,
customFetcher,
customMatcher,
);

console.log("Hydrated ads:", hydratedAds.sponsoredProducts);

Both hydrate the sponsored products and the Story ads' products in one fetcher call, and wait for it. Each one comes with the same advertisement (event URLs and parameters) and, when found, product. A Story also keeps story, the ad as the ad server sent it (video, cover, destination), and comes without product when it has none or it wasn't found.

Hydrating ads already fetched​

To show the ads first and their products when they arrive, call getRawAds() and then hydrateAds(), with the same fetcher and matcher:

import {
getRawAds,
hydrateAds,
intelligentSearchFetcher,
intelligentSearchMatcher,
} from "@vtex/ads-core";

const rawAds = await getRawAds(adRequest);
// Show rawAds.stories here.

try {
const { stories, sponsoredProducts } = await hydrateAds(
rawAds,
intelligentSearchFetcher,
intelligentSearchMatcher,
adRequest.identity,
{ signal: AbortSignal.timeout(5000) },
);
} catch {
// The product request failed: keep showing the raw ads.
}

Key Concepts​

  • Raw Ads: Basic ad data from the Ad Server without product enrichment
  • Hydrated Ads: Ads enriched with detailed product information
  • Fetcher: Function that retrieves product details for ad offers
  • Matcher: Function that determines if a product matches an ad offer
  • Placements: Named locations where ads will be displayed