La API Appcues proporciona un punto final HTTP para agregar eventos y perfiles de usuario individuales a su cuenta Appcues . Estos eventos y actualizaciones de perfil, o "actividad del usuario", se pueden utilizar para dirigir el contenido adecuado a los usuarios finales adecuados.

URL base

La URL raíz de la API Appcues es https://api.appcues.com/

Realizar solicitudes

El punto final de actividad del usuario acepta solicitudes POST, en formato JSON, que deben contener un encabezado Content-Type: application/json .

URL de envío
Las presentaciones deben incluir:

• su ID de cuenta Appcues (desde la página de la cuenta )
• El ID del usuario final (el primer parámetro de su Appcues .identify() de Appcues).
• Un encabezado `Content-Type: application/json`.

Nota : Si el ID del usuario final enviado no existe en Appcues , se creará un nuevo usuario con ese ID.

Una vez completado, la URL debería verse así:

https://api.appcues.com/v1/accounts/{account id}/users/{user id}/activity

Cuerpo de la solicitud

El cuerpo de la solicitud debe ser un objeto con formato JSON, que contenga uno o ambos de los siguientes parámetros:

• eventos Matriz de objetos de eventos, definidos a continuación.
• profile_update Objeto que contiene datos clave-valor arbitrarios para actualizar en el perfil almacenado del usuario.
• request_id (Opcional) Cadena arbitraria que permite identificar esta solicitud. El request_id se devolverá en la respuesta.

Envío de eventos

Cada evento que envías es un objeto incluido en una matriz de eventos. Cada objeto de evento debe contener los siguientes parámetros:

• Nombre del evento. Este es el mecanismo principal para pin y enfocar eventos específicos. Máximo 127 caracteres.
• marca de tiempo Hora en la que ocurrió el evento, ya sea en formato entero (como hora Unix) o en formato de cadena (como fecha compatible con ISO 8601, por ejemplo, 2016-01-13T13:05:22.000Z ).
• Atributos: Objeto que contiene datos clave-valor arbitrarios que describen los detalles del evento. Opcional.

"events": [
    {
      "name": "clicked widget",
      "timestamp": 1452854179,
      "attributes": {
        "widget_color": "blue",
        "ab_group": "a"
      }
    },
    {
      "name": "purchased a plan",
      "timestamp": 1452855000,
      "attributes": {
        "plan_tier": "Enterprise",
      }
    }
]

Nota sobre los nombres de eventos reservados : Appcues reserva eventos con nombres que comienzan con appcues : para uso interno.

Nota sobre las marcas de tiempo: Si le interesa usar el ejemplo anterior para un evento de prueba, le recomendamos usar una marca de tiempo actualizada. Es posible que los eventos con marcas de tiempo anteriores no aparezcan en las listas de Studio.

Envío de propiedades del perfil de usuario

Cada actualización de perfil que envía es un par clave-valor en el objeto profile_update , sin parámetros obligatorios.

"profile_update": {
  "team": "Product",
  "tier": "Beginner"
}

Ejemplo de solicitud

A continuación se muestra un ejemplo de una solicitud de API válida, que incluye eventos y actualizaciones de perfil, con el ID de cuenta 123 y el ID de usuario 456 :

curl https://api.appcues.com/v1/accounts/123/users/456/activity \
  -X POST -H "Content-Type: application/json" -d '
{
  "request_id": "abc123",
  "events": [
    {
      "name": "clicked widget",
      "timestamp": 1452854179,
      "attributes": {
        "widget_color": "blue",
        "ab_group": "a"
      }
    }
  ],
  "profile_update": {
    "favorite team": "Red Sox",
    "favorite boat type": "Duck"
  }
 }

Formato de respuesta

Un envío exitoso de actividad de usuario dará como resultado una respuesta de verdadero:

{"ok":true}

Manejo de errores

Una solicitud fallida tendrá una respuesta que contendrá información sobre el error ocurrido:

{"error":true,"message":{"description":"no route found for POST /v1/accounts/users/K/activity (ApiWeb.Router)","title":"no route found for POST /v1/accounts/users/K/activity (ApiWeb.Router)","type":"error"},"status_code":404}

Recomendamos crear una lógica de reintento para manejar posibles errores.