Cualquier (webshop)

API

Una forma flexible de integrar del lado del servidor.

Toda la comunicación con Clerk ocurre a través de la API:

https://api.clerk.io/v2

Configurar esta comunicación requiere 4 pasos, que se detallan en esta guía. Necesitas:

  1. Sincronizar datos
  2. Recuperar resultados
  3. Visualizar los resultados
  4. Agregar seguimiento

Claves API #

Estas claves se usan para acceder a los datos de tu Tienda. Se encuentran en my.clerk.io > Developers > API Keys.

Constan de una clave Pública, que da acceso a endpoints que exponen datos no sensibles, y una Clave Privada, que permite trabajar con los datos en la Tienda y acceder a datos sensibles, como información de clientes y pedidos.

Las Claves Privadas solo pueden consultarse una vez después de ser creadas por razones de seguridad, y puedes crear tantas como necesites para distintos propósitos.

1. Sincronizar datos #

El primer paso es obtener datos entrantes, permitiendo que la IA de Clerk.io entienda tu tienda online y prediga resultados. Clerk sincroniza cada dominio de tienda online como una instancia de Tienda única, a la que se accede mediante un conjunto de Claves API.

API CRUD #

Puedes sincronizar tus datos usando los endpoints de la API CRUD, que te permiten obtener, publicar, actualizar y eliminar recursos bajo demanda.

curl --request POST \
     --url 'https://api.clerk.io/v2/products' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "private_key": "osLqDAs5s2tlf3adpLv6Mp1hxx3f",
          "products":[
                {
                  "id": 123,
                  "name": "Green Lightsaber",
                  "description": "Antique rebel lightsaber.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. Fool proof."
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678],
                  "created_at": 11991864600
                }
             ]
           }'

Los objetos disponibles son:

Uno de los principales diferenciadores de Clerk es que no hay periodo de aprendizaje, ya que podemos utilizar todos los pedidos existentes desde el primer día para comprender el comportamiento actual de los clientes.

Data Feeds #

Además de usar la API CRUD, se recomienda encarecidamente agregar un método de sincronización de respaldo. Después de todo, muchas cosas pueden salir mal con las llamadas a la API.

Por ejemplo, tu servidor de precios podría fallar o un atributo de producto puede contener un error que cause el fallo de varias llamadas. Para evitar estos problemas, considera usar uno o más Data Feeds como copia de seguridad diaria para tus llamadas CRUD.

Los data feeds son uno o varios archivos JSON que contienen el catálogo actual de la tienda online.

Todos los datos disponibles en el feed cuando se cargan serán los que Clerk utilice, excepto los pedidos, que se registran y no necesitan incluirse en el feed después de la primera importación.

Utilizar el data feed también es una excelente forma de precargar Clerk con pedidos.

{
  "products": [ ... ],
  "categories": [ ... ],
  "orders": [ ... ],
  "customers": [ ... ],
  "pages": [ ... ],

  "config": {
    "created": 1567069830,
    "strict": false
  }
}

El/los data feed(s) deben estar disponibles en una URL a la que el importador pueda acceder, la cual se configura en el backend de my.clerk.io en System status > Data Sync. Puedes securizar el feed, para que solo nuestro importador tenga acceso.

2. Recuperar datos #

Una vez que los datos están sincronizados, la IA los analiza y construye índices inteligentes que puedes recuperar a través de endpoints únicos según el caso de uso.

Por ejemplo, para obtener los productos más populares puedes usar el endpoint recommendations/trending, y para mostrar los productos más destacados en una búsqueda de “star wars,” puedes usar el endpoint search/predictive.

Endpoints #

Todos los endpoints requieren que envíes la clave pública de API.

Los endpoints que devuelven resultados también requieren el argumento “limit” para controlar la cantidad de resultados a retornar.

Parámetros adicionales dependen del endpoint que llames. Por ejemplo, las mejores alternativas requieren products, que es una lista de IDs de productos para encontrar accesorios, y cualquier llamada relacionada con búsquedas necesita el parámetro query para encontrar coincidencias.

Puedes encontrar los argumentos necesarios para todos los endpoints en nuestra documentación de la API.

Por defecto, la API de Clerk retorna todos los resultados disponibles, pero si es necesario, puedes usar Filtros para definir un subconjunto de coincidencias.

A continuación un ejemplo de llamada a un endpoint de Search para encontrar los productos principales para una búsqueda de “star wars,”

curl --request POST \
     --url 'https://api.clerk.io/v2/search/predictive' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "query": "star wars",
          "labels": ["Search - Predictive"]
        }'

Recommendations #

A continuación un ejemplo de llamada a un endpoint de Recommendations para encontrar los productos más populares.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Homepage - Trending"]
        }'

Depuración de respuestas #

Cuando la depuración está habilitada en una solicitud, las respuestas de la API incluyen un array debug que muestra, en orden, cómo distintas características afectaron los resultados. Cada entrada incluye una feature, un message legible por humanos, y metadatos estructurados metadata que describen los efectos específicos.

{
  "status": "ok",
  "result": [
    "riverbank",
    "pretty-tree"
  ],
  "count": 2,
  "hits": 2,
  "debug": [
    {
      "feature": "merchandising",
      "message": "Applying merchandising campaign: Test-promote-in-results. Any calculated effects are available in the metadata.",
      "metadata": {
        "promote_in_result": {
          "frequency=(2, 0)": {
            "promoted_products": [
              [
                "riverbank"
              ]
            ]
          }
        }
      }
    },
    {
      "feature": "merchandising",
      "message": "Applying merchandising campaign: test-promote-to-position. Any calculated effects are available in the metadata.",
      "metadata": {
        "promote_to_position": {
          "position=(0, 1)": {
            "promoted_products": [
              [
                "0001",
                "FFFF"
              ]
            ]
          }
        },
        "adjust_position": {
          "FFFF": [
            {
              "max_depth": 1,
              "boost": 100000
            }
          ]
        }
      }
    },
    {
      "feature": "merchandising",
      "message": "Applying merchandising campaign: Test campaign. Any calculated effects are available in the metadata.",
      "metadata": {
        "boost": {
          "SPACER0": -2.0
        }
      }
    }
  ]
}

3. Visualizar resultados #

La API de Clerk siempre retorna los IDs de las coincidencias que encuentra al devolver resultados.

Para visualizar tus datos, puedes hacer llamadas a la API del lado del servidor, recuperar los IDs de los productos coincidentes y luego obtener toda la información específica del producto desde tu plataforma de tienda online o PIM antes de mostrarlos.

Llamada

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 3,
          "labels": ["Homepage - Trending"]
        }'

Respuesta

{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693
    ],
    "count": 3902,
    "facets": null
}

La API de Clerk también puede configurarse para enviar de vuelta cualquier información específica del recurso que envíes a Clerk, como precios, nombres de marca, URLs de categorías, imágenes de portada de blog y más.

Con esto, a menudo no tienes que hacer llamadas individuales a tu PIM antes de mostrar resultados, lo que hará que tu página cargue más rápido.

Llamada

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 3,
          "labels": ["Homepage - Trending"],
          "attributes": ["id", "name", "price", "image", "url"]
        }'

Respuesta

{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693
    ],
    "count": 3902,
    "facets": null,
    "product_data": [
        {
            "id": 12793,
            "image": "https://admin.awesomestore.com/image/14df",
            "name": "Baccarat Eye Small Oval Red Vase",
            "price": 520.0,
            "url": "https://admin.awesomestore.com/product/14df"
        },
        {
            "id": 13827,
            "image": "https://admin.awesomestore.com/image/51xs",
            "name": "Sabre Transat Garden Green 22cm Soup Spoon",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/51xs"
        },
        {
            "id": 12693,
            "image": "https://admin.awesomestore.com/image/62x1",
            "name": "Sabre Transat Light Blue 22cm Dinner Fork",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/62x1"
        }
    ]
}

4. Seguimiento #

Debe agregarse el seguimiento para mantener la IA de Clerk actualizada y personalizar los resultados de un visitante durante su sesión. Requiere 4 pasos:

  1. Generar un ID de sesión para cada visitante.
  2. Agregar etiquetas descriptivas a las llamadas de la API que devuelvan resultados.
  3. Registrar los clics de un visitante en los productos que muestra Clerk.
  4. Registrar cada pedido realizado en la tienda online.

Crear Visitor ID #

El ID de sesión también se llama Visitor ID. Es requerido para registrar la actividad de un usuario durante una sesión en la tienda online, incluyendo los productos que hace clic, sus búsquedas y categorías que navega.

Esta actividad se almacena para cada Tienda, y Clerk.io nunca la comparte entre Tiendas.

Un visitor ID es simplemente una cadena usada para identificar la sesión. Puede contener cualquier carácter alfanumérico, y recomendamos que no supere 8 caracteres para mejor rendimiento.

Por ejemplo, puedes usar la función de PHP uniqid() para generar IDs que sean únicos al menos para la sesión actual. Una vez generado, este ID debe ser incluido en todas las llamadas a la API de Clerk.io para que el seguimiento funcione.

<?php

session_start();

$current_visitor = uniqid(); //Ejemplo: "646f1f0584371"

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Agregar etiquetas #

Las etiquetas deben agregarse a todas las llamadas que devuelvan resultados, como coincidencias de búsqueda o alternativas en una página de producto. El argumento labels es una lista que debe contener al menos una cadena de texto, que será la etiqueta descriptiva de la llamada.

Recomendamos usar etiquetas que describan la página donde se usa la llamada, y el tipo de resultados que muestra. Un ejemplo podría ser Homepage - Trending. Así serán fáciles de distinguir en análisis.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Homepage - Trending"],
          "visitor": $_SESSION["clerk_visitor_id"]
        }'

Registrar clics #

Debes registrar cada clic sobre un producto de Clerk.io usando el endpoint log/click.

Es importante hacer esta llamada solo cuando el producto clicado es mostrado realmente por Clerk.io y no por la plataforma de la tienda online. De lo contrario, parecerá que todos los productos son encontrados a través de Clerk.

La llamada también debe contener el campo api, que es el endpoint usado para mostrar el producto sobre el que se ha hecho clic, y product, que contiene el ID del producto clicado.

Search & Recommendations #

Registrar los clics se realiza agregando los parámetros a la llamada según el endpoint usado para mostrar el producto. Es sencillo ya que se usan datos de tu propia configuración.

curl --request POST \
     --url 'https://api.clerk.io/v2/log/click' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "labels": ["Homepage - Trending"],
          "api": "recommendations/trending",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793
        }'

Email Recommendations #

Registrar clics funciona de manera diferente, ya que recibirás los datos de peticiones GET que son redirigidas por Clerk.io. Deberías monitorear si la URL incluye parámetros que indiquen que los visitantes aterrizan en una página de producto desde una Email Recommendation.

Estas solicitudes siempre contendrán los siguientes parámetros de consulta:

{
  "utm_source": "clerk",
  "utm_medium": "email",
  "utm_campaign": "Welcome Email - Bestsellers",
  "utm_content": "clerk-recommendations",
  "clerk_product": 12793,
  "clerk_labels": "Welcome Email - Bestsellers",
  "clerk_api": "recommendations/popular",
  "clerk_n": 0,
  "clerk_external": 1
}

Recomendamos monitorear si la URL incluye clerk_external: 1 y, en ese caso, registrar el clic con los datos que recibas.

clerk_api contiene el endpoint de la API con un carácter * para evitar problemas de codificación. Esto debe cambiarse por / al registrar el clic. external: 1 debe agregarse en la llamada para que Clerk sepa que el clic viene de un correo electrónico.

Aquí tienes un ejemplo de llamada a log/click que usa los datos anteriores:

curl --request POST \
     --url 'https://api.clerk.io/v2/log/click' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "labels": ["Welcome Email - Bestsellers"],
          "api": "recommendations/popular",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793,
          "external": 1
        }'

Registrar productos #

Cuando los visitantes visualicen páginas de producto, esto debe registrarse para poder personalizar resultados, especialmente los relacionados con el visitante como Visitor Recommendations o Visitor Alternatives.

Si usas cualquier endpoint que ya requiera el ID del producto, como recommendations/substituting o recommendations/complementary, Clerk.io registrará el ID automáticamente.

Sin embargo, si no es así, necesitas hacer una llamada separada a log/product con el ID del producto que se está visualizando.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793
        }'

Registrar ventas #

La IA de Clerk.io depende en gran medida de los pedidos para predecir resultados, por lo que rastrear estos en tiempo real es clave. El endpoint log/sale se usa para esto.

Con el Visitor ID incluido en esta llamada, Clerk entenderá qué productos fueron mostrados, clicados y finalmente comprados. Esto permite que la IA se mantenga siempre actualizada y cambie resultados en tiempo real según el comportamiento del cliente.

Esta llamada también asocia el Visitor ID con la dirección de correo electrónico o el ID de cliente del comprador, permitiendo una mejor personalización a través de recomendaciones específicas para el cliente.

El id de los productos debe coincidir con los IDs que se registran para clics. Por ejemplo, para productos configurables se debe rastrear el ID del padre tanto en log/click como en log/sale sin importar la variante comprada.
price es el precio unitario. Se multiplicará por quantity en Analytics.
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0",
          "sale": 567,
          "products": [
            {
              "id": 12793,
              "price": 99.95,
              "quantity": 2
            },
            {
              "id": 1546,
              "price": 14.00,
              "quantity": 2
            }
          ],
          "customer": 1234,
          "email": "theone@matrix.com",
          "visitor": $_SESSION["clerk_visitor_id"]}' \
       https://api.clerk.io/v2/log/sale

Esta página ha sido traducida por una IA útil, por lo que puede contener errores de idioma. Muchas gracias por su comprensión.