DocumentationAnalyticsImplementation Guide

Visitor identification using the Data Insertion API

Last update: September 28, 2026

CREATED FOR:

  • Admin
  • Developer
  • Leader

The Data Insertion API sends hits to Adobe Analytics collection servers without a client-side library such as AppMeasurement or the Web SDK. Because no library is present to manage identity for you, you set the visitor identifier yourself — in the browser for direct image requests, or on your server for server-side collection.

NOTE
This page covers visitor identity. For building and sending the requests themselves, see the Data Insertion API documentation on Adobe Developer.

Adobe identifies a visitor using the standard order of operations: the vid, then the aid, mid, fid, and finally the IP address and user agent. With the Data Insertion API you typically set one of three identifiers directly: the ECID (mid), the Analytics visitor ID (aid), or a custom visitor ID (vid).

The ECID (sent as the mid) is the modern, cross-solution visitor identifier, shared across Adobe Analytics, Adobe Target, and Adobe Audience Manager. Adobe recommends using it wherever possible.

Obtain the ECID with the Visitor ID Service (VisitorAPI.js). In a browser, initialize the service with your IMS organization ID using getInstance, then read the ECID with getMarketingCloudVisitorID:

var visitor = Visitor.getInstance("YOUR_ORG_ID@AdobeOrg");
var ecid = visitor.getMarketingCloudVisitorID();

Send that value on each hit as the mid query parameter, along with your IMS organization ID as the mcorgid parameter so the ECID resolves correctly. If your data forwards to Audience Manager, also send the region from getLocationHint as the aamlh parameter. To associate your own customer identifiers with the visitor, use setCustomerIDs.

For server-side collection, obtain the ECID on the client and forward it to your server to send on each hit. To generate an ECID entirely server-side, without a client, use the ID Service’s direct integration.

Using the Analytics visitor ID

The Analytics visitor ID (aid) is stored in the s_vi cookie. When a hit arrives without an identifier, the collection server assigns an aid and attempts to set a cookie containing that identifier. Some response types also include this identifier in the response body.

  • Client-side (direct image requests). The browser stores the s_vi cookie that the server returns and sends it on every later request to the same collection domain. The visitor is then recognized automatically, with no aid to set yourself. Because this model depends on cookies, it carries the same durability limits as any cookie-based identity. See Visitor identification using AppMeasurement for first-party versus third-party cookie behavior, and the order of operations for how Adobe chooses which identifier to use. Adobe recommends using an ECID for durable identity.

    note
    NOTE
    If you read the visitor ID directly from the s_vi cookie, the cookie wraps the ID in additional data (for example, [CS]v1|<id>[CE]) — extract only the <id> portion. Reading the ID from a visitor response returns it directly, with no parsing.

  • Server-side. A server has no cookie jar, so you store and resend the aid yourself, keyed to the user:

    1. Look up the stored aid for the user.
    2. If you have one, send it as the aid query parameter.
    3. If you do not, send the hit with no identifier, requesting a response type that returns the assigned aid, then store it for next time.

    The first, identifier-less hit is already attributed to the aid the server returns, so you lose no data by sending it before you have an ID. For the response types that return the ID (3 for JavaScript, 11 for XML, 10 for JSON) and the request format, see Response type in the Data Insertion API documentation.

    A server-side request carries no visitor cookies, and its own IP address and user agent belong to the sender. To attribute hits correctly, also forward the visitor’s real IP address (the X-Forwarded-For header) and user agent (the User-Agent header).

Using a custom visitor ID

If you already have a durable identifier that you fully control, you can send it as the visitorID (vid) on every hit and own identity end to end. This suits non-browser platforms that provide a stable device identifier. For example, a Unity application can send its device identifier as the vid.

IMPORTANT
Use vid only when you can guarantee a stable value on every hit:
  • Browsers are a poor fit. A browser has no durable identifier you can populate reliably, so a browser-set vid tends to fragment or collide. Use the cookie-based client-side model instead.
  • Be careful with authentication identifiers. You have no identifier before a user logs in, and if the user logs out, later hits are attributed to a different visitor. These actions split one person’s activity across multiple visitors.

See visitorID for the format and constraints of a custom visitor ID.

recommendation-more-help
analytics-help-implement