Complete Guide: Creating Custom Integrations with Convert.com

IN THIS ARTICLE YOU WILL:

• Learn to Implement BYOID
• Extract Data and Segments
• Map APIs
• Track Conversions
• Learn Best Practices

This guide provides a standardized approach for connecting Convert.com to your internal backend or third-party analytics platforms. It utilizes the Project ID method, compatible with all standard Web Testing projects, which does not require complex API authentication

1. Frontend: Implementing Bring Your Own ID (BYOID)

To ensure 100% data consistency between your backend and Convert.com, you should use your own internal identifier (like a Database User ID or a hashed email) instead of relying on Convert's default cookies.

Crucial: Sequence of Execution

The BYOID must be defined before the main Convert tracking tag loads on your page. This ensures that the very first "bucket" event recorded by Convert is already associated with your custom ID.

Correct Implementation Order:

<script>
  window._conv_q = window._conv_q || [];
  window._conv_q.push({
    what: 'setCustomVisitorId',
    params: { visitorId: 'YOUR_INTERNAL_USER_ID' } // Replace with your actual dynamic ID
  });
</script>

<script type="text/javascript" src="//cdn-4.convertexperiments.com/js/12345678-12345678.js"></script>

2. Frontend: Extracting Data and Segments

Use these utility functions to extract the active experiments and visitor segments. This allows you to forward Convert's data to third-party tools (like Segment, Mixpanel, or GA4) using your own identifier.

const convert_utils = {
  getBrowser: () => window.convert.currentData.segments.browser || 'OTH',
  getDevice: () => window.convert.currentData.segments.devices || ['OTHDEV'],
  getSource: () => window.convert.currentData.segments.source || 'direct',
  getVisitorType: () => window.convert.currentData.segments.visitorType === 'returning' ? 1 : 0,
  getCountry: () => window.convert.currentData.segments.country || '',
};

// Listener: Fires when experiments are bucketed
window._conv_q.push({
  what: 'addListener',
  params: {
    event: 'snippet.experiences_evaluated',
    handler: function() {
      const experiences = window.convert.currentData.experiences;
      const dataPayload = {
        experiments: [],
        segments: {
          browser: convert_utils.getBrowser(),
          devices: convert_utils.getDevice(),
          visitorType: convert_utils.getVisitorType()
        }
      };

      for (const id in experiences) {
        dataPayload.experiments.push({
          experienceId: id,
          variationId: experiences[id].variation.id
        });
      }

      // Action: Forward this to your third-party tool
      // myAnalyticsApp.track('Convert Data', dataPayload);
    }
  }
});

3. API Mapping Table (Segment Codes)

When sending data via the API, use these short-codes to ensure they match Convert’s internal database.

4. Backend: Tracking Conversions (Serving API)

When a conversion occurs on your server (e.g., a processed payment), use the Serving API to notify Convert. This method uses your Project ID directly and does not require an Authorization header.

API Endpoint

POST https://{project_id}.metrics.convertexperiments.com/track

The Request Structure

By using the same internal ID in the vid field as you did on the frontend, Convert will perfectly stitch the session data together.

Headers:

• Content-Type: application/json
• User-Agent: <Any-Value> (Required to bypass firewall)

Request Body (JSON):

{
  "cid": "10012345", // Your Account ID
  "pid": "10056789", // Your Project ID
  "vid": "YOUR_INTERNAL_USER_ID", // The SAME ID used in the frontend tag
  "seg": {
    "browser": "CH",
    "devices": ["DESK"],
    "new": 1
  },
  "ev": [
    {
      "evt": "hitGoal",
      "goals": ["99887766"], // Goal ID
      "exps": ["11223344"],  // Experience ID
      "vars": ["55667788"]   // Variation ID
    }
  ]
}

5. Best Practices

• Persistent Identity: Setting BYOID before the Convert tag prevents "anonymous" hits and ensures every event is tied to your user.
• No Auth Header: For standard Web projects, use the /track/{pid} endpoint to avoid exposing API keys in client-side code (though this call is typically backend-to-backend).
• Reference Document: For deeper technical details on ID persistence, refer to the Convert BYOID Documentation.