Compatibilité Segment | Convertmax Docs

Convertmax accepte les payloads d’événements de type Segment sur l’API Événements (event.convertmax.io) et les normalise dans le schéma de suivi Convertmax avant de les ingérer. Ceci est distinct de l’API Convertmax utilisée pour les données produits, contacts et commandes de la plateforme.

Utilisez ce guide lorsque vous envoyez déjà des appels Segment track, identify, page, screen, group ou batch et que vous voulez que Convertmax reçoive les mêmes événements avec un minimum de changements.

Points de terminaison pris en charge

Convertmax accepte le JSON compatible Segment sur ces points de terminaison :

POST /v1/track/
POST /v1/identify/
POST /v1/page/
POST /v1/screen/
POST /v1/group/
POST /v1/batch/

POST /v1/track/ peut détecter automatiquement un payload Segment depuis le corps de la requête. Les autres routes imposent le type d’événement Segment attendu.

Authentification

Utilisez les mêmes options d’authentification que l’API d’événements standard :

Authorization: Bearer <api_key>
?key=<api_key>

Compatibilité RudderStack et PostHog

RudderStack : naturellement compatible car RudderStack suit le design de l’API Segment.
PostHog : compatible comme source de données d’événements lorsque PostHog envoie des payloads au format Segment. Utilisez la compatibilité API Segment pour ingérer les événements PostHog dans Convertmax.

Comment Convertmax mappe les événements Segment

Convertmax transforme les payloads Segment vers le format d’événement interne selon ces règles :

Type Segment	`event_type` Convertmax	Notes
`track`	mappé depuis `event`	Les noms courants comme `Purchase` sont mappés vers `convert` ; les noms inconnus retombent vers `custom`
`identify`	`custom`	Les traits sont préservés dans `data.traits`
`page`	`page_view`	Les métadonnées de page sont préservées dans `data`
`screen`	`page_view`	Le nom d’écran est préservé dans `data.screen_name`
`group`	`custom`	Les traits de groupe sont préservés dans `data.group_traits`
`batch`	par élément d’événement	Chaque élément est normalisé et ingéré indépendamment

Normalisation du nom d’événement pour `track`

Convertmax mappe les noms d’événements Segment courants ainsi :

Purchase, Order Completed, et les noms de type checkout deviennent convert
Add To Cart et les noms de type panier deviennent add_cart
les noms de type page deviennent page_view
les noms de type clic deviennent click
les noms de type recherche deviennent search
tout le reste devient custom

Mapping visiteur et session

Convertmax extrait les valeurs d’identité depuis le payload Segment ainsi :

visitor utilise userId en premier, puis anonymousId
session_id utilise context.sessionId, context.session_id, ou sessionId

Métadonnées préservées dans `data`

L’événement Convertmax normalisé conserve le contexte Segment original dans data, incluant :

source: "segment"
segment_type
message_id
timestamp, sent_at, et original_timestamp
event_name
user_id, anonymous_id, et group_id
properties, traits, ou group_traits lorsque présents
integrations
context
des champs de page dérivés tels que page, page_title, page_path, et page_referrer

Exemple track

curl -X POST "https://event.convertmax.io/v1/track/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "Purchase",
    "userId": "user_123",
    "anonymousId": "anon_123",
    "messageId": "msg_001",
    "context": {
      "sessionId": "sess_abc",
      "page": {
        "url": "https://example.com/checkout/success",
        "title": "Order complete"
      }
    },
    "properties": {
      "revenue": 100,
      "currency": "USD"
    }
  }'

Ce payload est normalisé en un événement Convertmax avec :

event_type: "convert"
visitor: "user_123"
session_id: "sess_abc"
les métadonnées Segment stockées dans data

Exemple identify

curl -X POST "https://event.convertmax.io/v1/identify/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "traits": {
      "email": "buyer@example.com",
      "plan": "pro"
    }
  }'

Ceci est ingéré comme un événement Convertmax custom avec les traits originaux préservés dans data.traits.

Exemple page

curl -X POST "https://event.convertmax.io/v1/page/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "anonymousId": "anon_123",
    "name": "Pricing",
    "context": {
      "page": {
        "url": "https://example.com/pricing",
        "path": "/pricing",
        "title": "Pricing"
      }
    }
  }'

Ceci est ingéré comme un événement Convertmax page_view.

Exemple batch

curl -X POST "https://event.convertmax.io/v1/batch/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "batch",
    "userId": "user_123",
    "context": {
      "sessionId": "sess_abc"
    },
    "batch": [
      {
        "type": "page",
        "name": "Home",
        "context": {
          "page": {
            "url": "https://example.com/"
          }
        }
      },
      {
        "type": "track",
        "event": "Add To Cart",
        "properties": {
          "product_id": "sku_001",
          "quantity": 1
        }
      }
    ]
  }'

Pour les requêtes batch, Convertmax applique les valeurs userId, anonymousId, context, et integrations de niveau racine à chaque élément lorsque ces champs sont manquants sur l’événement individuel.

Référence associée

API Événements
Suivi des événements
API Convertmax — API plateforme distincte sur api.convertmax.io