Skip to content
adscapi
← Platforms
Real Conversions API

VK setup

Set VK’s tokens once. Then every ads.conversions.track() call fans the event out to VK server-side — no per-platform code.

Setup guide

Overview

adscapi sends server-side ecommerce events to VK Ads FSA (Full Stream Attribution — offline events for dynamic retargeting): POST https://ad.mail.ru/fsa/, one JSON object per event. The only accepted user identifier is a SHA-256 hashed phone; email is not supported. The phone is normalized to the Russian MSISDN form 79XXXXXXXXXX before hashing. VK matches these events to your product catalog and retargeting audiences.

Prerequisites

  • A VK Ads account with dynamic retargeting and a product catalog set up.
  • An FSA token issued by your VK Ads manager (see below).

1. Create an account

  1. Go to ads.vk.ru and create an advertising account.
  2. Set up a product catalog and a dynamic retargeting campaign. The productId you send on each event must match a product id in that catalog.

2. Get your credentials

VK does not self-serve the FSA token. Ask your VK Ads manager to enable Full Stream Attribution for your account. VK delivers the token through a one-time link that is valid for 4 days — open it and save the token immediately, because the link expires.

Secret Where to get it
VK_FSA_TOKEN Issued by your VK Ads manager via a one-time link (valid 4 days). Save it as soon as it arrives.

Sent as: Authorization: Token <VK_FSA_TOKEN> (the scheme word is Token, not Bearer).

3. Configure adscapi

export VK_FSA_TOKEN="…"   # the FSA token from the one-time link

4. Verify

adscapi verify --platform vk

Send a test purchase with user.phone and properties.productId set, then confirm it lands in your VK Ads dynamic-retargeting stats. A 401 means the token is wrong or expired — see Troubleshooting.

5. Event mapping

VK FSA accepts exactly four ecommerce actions (customEventName). adscapi maps its canonical events to the closest fit:

Canonical VK FSA (customEventName)
purchase purchase
checkout_created addToCart
page_view viewOffer

VK also supports addToWishlist, which has no canonical adscapi event. An unmapped canonical name is passed through as-is; VK rejects any value outside its four actions.

Troubleshooting

  • HTTP 401 — token invalid or expired. FSA tokens arrive via a one-time link that expires after 4 days; if you missed it, ask your VK manager to reissue the token and update VK_FSA_TOKEN.
  • No phone, no event — FSA requires a hashed phone as the only identifier. adscapi no-ops any event without a usable user.phone; send a raw phone number, never a pre-hashed one.
  • Phone not matching — VK wants the Russian MSISDN form 79XXXXXXXXXX. adscapi converts a domestic leading 8 to 7 and prefixes a bare 10-digit number with 7. Numbers that do not resolve to 7 + 10 digits are dropped.
  • Product not found — productId must match an id in your VK product catalog. adscapi reads it from properties.productId; if it is absent, the field is omitted and VK cannot attribute the event to a catalog product.
  • event is a single object — FSA does not accept arrays. adscapi sends one event per request.

1. Install adscapi

shell
npm install adscapi
# or run without installing:
npx adscapi platforms

2. Get VK's tokens

VK activates once all of these are set. Run npx adscapi platforms to see them, then get each value from VK’s ads or events dashboard.

VK_FSA_TOKEN

3. Set them for adscapi

Export the tokens in the environment that runs your server or the adscapi CLI.

shell
export VK_FSA_TOKEN="…"

4. Verify

check confirms the secrets are present; verify calls VK’s API to confirm they are valid.

shell
npx adscapi check
npx adscapi verify --platform vk

5. Track a conversion

One call, sent to VK and every other configured platform. Pass raw email — adscapi hashes per platform. Consent is required.

ts
import { createAdscapi } from 'adscapi';

const ads = createAdscapi();

const results = await ads.conversions.track({
  name: 'purchase',
  value: 49,
  currency: 'USD',
  user: { email: 'buyer@example.com' },
  consent: { adUserData: true, adPersonalization: true },
});

See the exact request on the VK payload preview.