Skip to main content

​
Primera activación CDP de extremo a extremo

El CDP tiene cuatro fases — ingest, resolución de identidad, segmentación y activación — y cada una cuenta con su propia guía que profundiza en su propia superficie. Lo que ninguna hace por sí sola es acompañarle en un pase continuo: enviar un evento, verlo coserse a una persona, construir una audiencia sobre ese historial y empujar la audiencia a un destino contra el que gastar presupuesto. Este tutorial hace ese pase una vez, de principio a fin, en una sola sesión. Haga este recorrido primero. Una vez que el bucle esté en servicio, las guías de fase se convierten en sus referencias de profundización:

​
Por qué importa un solo pase de extremo a extremo

Cada guía de fase da por sentado que existen las demás. Leídas por separado, le dejan coser el bucle a usted: la guía de fuente explica cómo aceptar eventos pero no qué hacer una vez que aterrizan; la guía de segmentos asume perfiles resueltos y eventos limpios; la guía de activación asume un segmento que merezca publicarse. Los workspaces CDP nuevos fracasan en los huecos entre guías — eventos ingestados pero nunca cosidos, segmentos construidos sobre duplicados sin resolver, activaciones que publican membresías exiguas que nadie diagnosticó aguas arriba. Ejecute este pase contra una fuente de prueba y un destino de prueba antes de abrir el tráfico real. Cuando algo se desvíe más adelante, reentrará en la guía de fase de esa fase — pero reentrará sabiendo qué fase está rota, porque ha visto el bucle completo sano una vez.

​
1. Requisitos previos

Tenga los tres antes del primer evento:
  1. Un tracking plan publicado. Declare los eventos que enviará su aplicación y la forma de propiedades por evento, en modo de aplicación soft, en la superficie de tracking plan. El modo soft registra las violaciones sin rechazar eventos, de modo que un productor nuevo nunca se detiene en un desajuste mientras usted itera. Apriete a strict más adelante.
  2. Una fuente conectada. Un secreto de ingest emitido en Integrations → CDP → Source (inbound) y desplegado en su aplicación — la guía de fuente y destinos recorre la emisión y la rotación. Su aplicación publica eventos firmados en https://api.orbit.devotel.io/cdp/v1/<ingest_id>/track.
  3. Un destino con credenciales. Una audiencia de red publicitaria alcanzada mediante una conexión OAuth, o un sink webhook HTTPS que usted controle. Conecte las credenciales antes de necesitarlas — la fase de activación solo mapea un segmento sobre un destino que ya autentica.
Tenga además una clave API con rol owner, admin o developer. Cada mutación de este recorrido (reglas, segmentos, activaciones) está restringida a esos roles; las lecturas aceptan más.

​
2. Ingestar una fuente

Elija un tipo de fuente en Integrations → CDP — Segment, RudderStack, un webhook genérico o su propio SDK publicando directamente. Emita el secreto de ingest desde la pestaña Source (inbound), despliéguelo en la aplicación y firme cada petición según la guía de firmado de ingest: las tres cabeceras X-Orbit-CDP-Timestamp, X-Orbit-CDP-Nonce y X-Orbit-CDP-Signature sobre <timestamp>.<nonce>.<raw body>, con clave en el secreto en claro. Dispare un evento track desde la aplicación. Después confirme que aterrizó — nunca lo suponga:
  1. Abra Integrations → CDP → Event debugger.
  2. Filtre Type = track y haga coincidir el nombre de su evento.
  3. Expanda la fila y lea exactamente las properties y el context que guardó la pasarela.
Si falta la fila, el fallo está en la capa de firma (un 401 que la aplicación tragó) o el tracking plan está rechazando el payload — la guía de event debugger y DLQ cubre ambos, incluida la lectura de un cuerpo de payload derramado o perdido. No avance hasta ver aquí un evento real.
Cuando el consentimiento gobierna su ingest — por ejemplo, si propiedades de evento proceden de campos de contacto cubiertos por una limitación de finalidad — registre la base jurídica por contacto mediante la API de consentimiento antes de encender la fuente. Orbit facilita el registro pero no sustituye un consentimiento válido: usted sigue siendo responsable de lo que ingesta y del uso que le da. Esta página no es asesoría jurídica.

​
3. Resolver la identidad

Los eventos llegan con la userId que envió su SDK, sea cual sea. Que esa se cosa a un contacto — y a qué contacto — lo deciden las reglas de identidad, no el evento en sí. La regla por defecto resuelve userId solo contra identificadores externos; una userId con forma de email o de teléfono no se cose hasta que usted habilite esa forma de coincidencia.
  1. Abra Integrations → CDP → Identity resolution y revise las formas de coincidencia: External ID (sembrada, prioridad 100), más Phone, Email y Anonymous ID en opt-in.
  2. Si sus eventos portan email o teléfono como identidad, simule primero en Audience → Identity resolution — el dashboard se niega a guardar un cambio en esas formas hasta que una simulación haya corrido en su sesión, porque una forma demasiado amplia cose a personas equivocadas de forma irreversible. Lea el recuento estimado de fusiones; si sobre-fusiona, estreche la forma o suba su prioridad.
  3. Guarde el conjunto de reglas de vuelta en la página CDP y, en el mismo constructor, fije la política de supervivencia (qué valor gana una fusión por campo).
  4. Confirme que la resolución aterrizó: abra Audience → Identity resolution y compruebe que la identidad de su evento de prueba se plegó en un solo contacto, no en un duplicado en la cola de revisión. La guía de catálogo de datos y reglas de identidad cubre prioridades, la puerta de simulación y la separación entre política y cola de revisión.
No omita nada aquí: cada segmento de abajo lee contactos resueltos, así que los duplicados sin resolver sobreviven en cada recuento de audiencia que construya.

​
4. Construir el segmento sobre eventos resueltos

Con eventos aterrizando e identidades cosiéndose, construya la audiencia. Un segmento es un filtro guardado sobre atributos de contacto, campos personalizados y eventos de comportamiento; créelo con POST /api/v1/contacts/segments. Dos ejemplos trabajados — un filtro simple y un trait SQL que lo alimenta.

​
Un filtro de comportamiento trabajado

Tres puntos a notar. Los eventos se referencian con el prefijo event.<name> y se emparejan con un operador de comportamiento — performed_event, did_not_perform_event, event_count o performed_sequence para recorridos ordenados. La ventana within es relativa, así que «los últimos 14 días» no exige aritmética de timestamps. Y auto_refresh materializa la membresía en una cadencia — la activación del paso siguiente lee esa membresía materializada, así que fíjelo. Dimensione el filtro antes de guardarlo. POST /api/v1/contacts/segments/preview evalúa el mismo filtro contra datos en vivo y devuelve un recuento de coincidencias sin persistir; un recuento de cero o «todo el tenant» significan ambos que el filtro está mal, no los datos.

​
Un trait SQL concreto que alimenta el segmento

Cuando el dato que necesita ya existe como SQL de warehouse — una vista de LTV propiedad de finanzas, un modelo dbt — adóptelo como trait SQL en vez de reconstruirlo en el DSL de predicados. Un único SELECT de solo lectura que devuelve (user_id, trait_value), ejecutado a su cadencia, estampa cada valor en el mapa de traits del contacto:
Una vez materializado el trait, se segmenta como cualquier atributo — { "field": "traits.ltv_tier", "op": "equals", "value": "high" } se combina libremente con las condiciones de comportamiento de arriba. El árbol completo de elección de motor (predicado DSL, SQL, AI) está en la página de traits SQL; el vocabulario completo de filtros está en la guía de segmentos.

​
5. Activar hacia un destino

La activación publica el segmento donde gana presupuesto — la audiencia de una red publicitaria o su sink webhook — en una cadencia que usted controla. Recórrala en dos llamadas, según la guía de pipeline de activación. Conecte el destino una vez. Para una red publicitaria (se muestra Google; Meta, TikTok, LinkedIn y el resto del catálogo se comportan igual):
Para su propio sink HTTPS en cambio, PATCH /api/v1/cdp/audience/webhook con target_url y un signing_secret; las entregas llegan firmadas X-Orbit-Signature: t=<unix-sec>,v1=<hmac-sha256>, el mismo esquema que su verificador de webhooks de Orbit ya comprueba. En cualquiera de los dos casos, los identificadores se hashean con SHA-256 antes del despacho a redes publicitarias — el PII en claro nunca sale del tenant. Ejecute la primera activación explícitamente en lugar de esperar al calendario:
Haga primero un dry-run con POST /api/v1/cdp/audience/preflight/google siempre que el veredicto sea incierto — la misma puerta, nada se despacha. La puerta de pre-activación bloquea audiencias de tamaño insuficiente, cobertura baja de identificadores y violaciones de consentimiento o supresión; los ids de los controles fallados vuelven en la respuesta. Si esta organización tiene maker-checker activo, la ejecución se encola para la aprobación de una segunda persona — envíe, haga aprobar por un owner y reenvíe con el id de aprobación devuelto.

​
6. Lectura de confirmación y resolución de problemas

Confirme que la ejecución aterrizó y luego aprenda el presupuesto de latencia para distinguir lo sano de lo atascado. Confirmar. GET /api/v1/cdp/audience/activations lista el historial de ejecuciones; GET /api/v1/cdp/audience/activations/:id profundiza en una ejecución con los recuentos requested / matched / skipped y los motivos de rechazo por miembro (nunca PII). Un estado ok con matched cercano a requested es sano; partial nombra su cubo; skipped significa que nada coincidió o que ninguna conexión se resolvió en el despacho. Para un destino warehouse en lugar de red publicitaria, lea los mismos veredictos en el registro de ejecuciones de sincronización — por ejecución attempted / delivered / rejected / failed y las clases de error (auth, validation, rate_limit, …) que deciden el bucle de reintento. El presupuesto de latencia. Cada fase tiene su propio retraso esperado; una queja solo se convierte en bug cuando una fase excede su presupuesto: Leer la tabla de arriba abajo convierte «la audiencia está mal» en «la fase N está fuera de presupuesto» en un solo pase. Reentre entonces en la guía dedicada de esa fase — fuente y destinos, reglas de identidad, segmentos, activación o reverse ETL — con el fallo ya localizado. Las cuatro formas de fallo que encontrará de verdad. Un 409 CONNECTION_NOT_CONFIGURED al activar significa que el destino no está del todo conectado (falta audience_id o el id de conexión). Un 422 AUDIENCE_PREFLIGHT_BLOCKED nombra su control de puerta fallado — redimensione el segmento, arregle la cobertura de identificadores o anule deliberadamente. Cero miembros coincidentes significa que llegaron filas sin identificador fuerte — arregle el mapeo en el ingest, no en la activación. Una ejecución partial cuyo detalle muestra cubos validation con “missing or empty upsert identifier” significa que la clave de upsert no está mapeada — arregle el mapeo de campos y reejecute. Las cuatro están cubiertas por fase en las guías enlazadas arriba.

​
Véase también