Skip to content
adscapi

Identity & hashing

Every identifier you add gives the platform another way to match the event. Pass raw fields on user and clickIds — adscapi normalizes and SHA-256 hashes each one per the platform's rules. You never hash anything yourself.

Rule: raw in, hashed out

  • Never pre-hash email, phone, or name. Double-hashing silently kills match rate
  • adscapi lowercases / trims / E.164-normalizes where each platform requires it, then hashes
  • Click ids (gclid, fbclid, …) and fbc/fbp are sent as-is — they are not PII hashes

ConversionUserData

FieldType
emailstring?
phonestring?
firstNamestring?
lastNamestring?
citystring?
statestring? (region is an alias)
zipstring?
countrystring?
dateOfBirthstring?
gender'm' | 'f'
externalIdstring?
ipstring?
userAgentstring?
fbcstring?
fbpstring?

Priority if you can only capture some

PriorityFields
1 — strongestemail + phone + click IDs (gclid, fbclid, ttclid, …)
2ip + userAgent
3firstName, lastName, city, state, zip, country
4externalId, dateOfBirth, gender, fbc/fbp

Capture click ids client-side with pixel helpers (pixelSnippet() / parseClickIds()) so they survive into the server event.

Example

ts
await ads.conversions.track({
  name: 'purchase',
  value: 49,
  currency: 'USD',
  user: {
    email: 'jane@example.com',          // raw — never pre-hash
    phone: '+1 415 555 2671',
    firstName: 'Jane',
    lastName: 'Doe',
    city: 'Austin',
    state: 'TX',                        // region is an alias
    zip: '78701',
    country: 'US',
    dateOfBirth: '19900115',
    gender: 'f',
    externalId: 'cust_123',
    ip: req.ip,
    userAgent: req.headers['user-agent'],
    fbc,                                // Meta click cookie
    fbp,                                // Meta browser id cookie
  },
  clickIds: {
    fbclid, gclid, ttclid, msclkid,
    twclid, epik, sccid, li_fat_id, rdt_uuid,
  },
  consent: { adUserData: true, adPersonalization: true },
});

Related