Implementing Cross-Device Identity & Consent

Overview

Welcome to our guide on integrating Concord's Cross-Device Identity feature. We make it easy to leverage cross-device consent states in just a few minutes and this guide will help you get up and running quickly.

The Concord Identity system connects anonymous browser sessions to persistent consent records. When a visitor identifies themselves (e.g., via login), the identify method maps the current Context (device) to a known Identity (person). If that person has existing consent records on another device, Concord merges the identities, allowing the most recent consent state to prevail.

Prerequisites

Before beginning the integration, ensure the following requirements are met:

1. Administrative Access: Cross-device consent must be enabled in your Concord Organization settings (Advanced Settings > Cross-Device Consent).
2. SDK Installation: The Concord site-client snippet must be initialized on your site.
3. Authentication Keys: You must generate an asymmetric key pair (EC P-256) for signing JSON Web Tokens (JWTs).

Step 1: Secure Token Generation

Concord requires JWT authentication to verify identity requests. Your server must sign a short-lived JWT using your private key, which the SDK then passes to the Concord API.

1. Generate an EC P-256 Key Pair

Use OpenSSL to generate the required keys:

# Generate EC private key
openssl ecparam -genkey -name prime256v1 -noout -out identify-key.pem

# Extract public key
openssl ec -in identify-key.pem -pubout -out identify-key-pub.pem

2. Configure the JWT Payload

The JWT payload must include the following claims:

• sub: The unique identifier for the user (e.g., a UUID or email).
• iat: Issued-at timestamp.
• exp: Expiration timestamp (recommended 60 seconds).
• iss: Your Concord Organization ID.

Step 2: Frontend Implementation

Once your backend is capable of generating a signed JWT, use the identify method in the frontend to link the session.

Calling the Identify Method

Trigger this method immediately after a user authenticates (Login, Signup, or Email Verification).

// Example: Identifying a user after login
const userJwt = await fetchUserJwtFromServer(); // Your internal API call

window.concord.identify(userJwt, {
  email: 'user@example.com', // Optional: Concord hashes this automatically
  format: 'plain'            // Use 'hashed' if sending pre-hashed PII
}).then((result) => {
  if (result.synced) {
    console.log('Identity and consent synchronized successfully.');
  }
});

Handling Pre-Initialization Identity

If the identity is known before the SDK loads (e.g., a server-rendered page), set the concordIdentity object on the window. The SDK will process this during its initialization sequence.

window.concordIdentity = {
  type: 'email',
  value: 'user@example.com',
  jwt: 'YOUR_SIGNED_JWT'
};

Step 3: Identity Merging and Syncing

When identify() is called, the Concord API performs an Identity Merge.

• Target vs. Source: If the user is already known in the Concord database (the "Target"), the current session (the "Source") is merged into the Target.
• Consent Sync: After a successful merge (synced: true), the SDK automatically calls store.refreshData() to pull the Target identity's consent state into the current browser.
• Events: The SDK dispatches a concord-identity-synced event upon completion.

Step 4: Session Reset

To prevent consent "leakage" in shared device environments, you should clear the identity and consent state when a user logs out.

// Clear local identity and return to anonymous state
window.concord.reset();

Configuration Parameters

Troubleshooting

synced: false returned

• First Identification: If this is the first time the identity has been seen by Concord, no match exists to merge with. This is expected behavior.
• Hash Mismatch: Ensure the format parameter matches the data type sent. A mismatch between plain and hashed values will prevent a merge.

Consent banner persists after login

• Verify that identify() returned synced: true.
• Check the Network tab for the /identify request to ensure the consentState object is populated in the response.
• Ensure the consent types in the Target identity profile match the active Region Template for your project.