Cualquier (webshop)

API

Una forma flexible de integrar del lado del servidor.

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

https://api.clerk.io/v2

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

  1. Sincronizar los datos
  2. Recuperar resultados
  3. Visualizar los resultados
  4. Añadir seguimiento

API Keys #

Estas claves se utilizan para acceder a los datos de tu Store. 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 el Store y acceder a información sensible, como datos de clientes y pedidos.

Las claves privadas solo pueden ser vistas una vez después de ser creadas por motivos de seguridad, y puedes crear tantas como necesites para diferentes propósitos.

1. Sincronizar datos #

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

CRUD API #

Puedes sincronizar tus datos usando los endpoints CRUD API, los cuales 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 un 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 CRUD API, se recomienda encarecidamente añadir un método de sincronización de respaldo. Al fin y al cabo, muchas cosas pueden fallar con las llamadas API.

Por ejemplo, tu servidor de precios podría fallar, o un atributo de un producto podría contener un error que haga que varias llamadas fallen. Para evitar estos problemas, considera usar uno o varios Data Feeds como respaldo diario de tus llamadas CRUD.

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

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

Usar el data feed también es una excelente manera 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 pueda acceder el importador, que se configura en el backend de my.clerk.io en System status > Data Sync. Puedes asegurar el feed, de modo que solo nuestro importador pueda acceder a él.

2. Recuperar datos #

Una vez que los datos están sincronizados, la IA los analiza y construye índices inteligentes que pueden ser recuperados a través de endpoints únicos dependiendo del caso de uso.

Por ejemplo, para obtener los productos más populares, puedes usar el endpoint recommendations/trending, y para mostrar los mejores productos para 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 el número de resultados a devolver.

Los parámetros adicionales dependen del endpoint que estés llamando. Por ejemplo, para las mejores alternativas se requiere products, que es una lista de IDs de producto para encontrar accesorios, y cualquier llamada relacionada con búsqueda 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 devuelve todos los resultados disponibles, pero si es necesario, se pueden usar Filtros para definir un subconjunto de coincidencias.

A continuación se muestra 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 se muestra 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 para una solicitud, las respuestas de la API incluyen un array debug que muestra, en orden, cómo diferentes funciones han afectado los resultados. Cada entrada incluye un feature, un message legible y un metadata estructurado que describe 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 devuelve los IDs de las coincidencias que encontró 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 se puede configurar para devolver cualquier información específica del recurso que envíes a Clerk, como precios, nombres de marcas, URLs de categorías, imágenes de portadas de blogs y más.

Con esto, a menudo no necesitas hacer llamadas individuales a tu PIM antes de mostrar los 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 #

El seguimiento debe añadirse para mantener la IA de Clerk actualizada y personalizar los resultados de los visitantes durante su sesión. Requiere 4 pasos:

  1. Generar un ID de sesión para cada visitante.
  2. Añadir etiquetas descriptivas a las llamadas a la API que devuelven resultados.
  3. Registrar los clics de los visitantes en productos mostrados por 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 necesario para registrar la actividad del usuario durante una sesión en la tienda, incluyendo los productos en los que hace clic, las búsquedas y las categorías que visita.

Esta actividad se almacena por cada Store y Clerk.io nunca la comparte entre Stores.

Un Visitor ID es simplemente una cadena que se utiliza para identificar la sesión. Puede ser cualquier carácter alfanumérico, y recomendamos mantenerlo con un máximo de 8 caracteres para el mejor rendimiento.

Por ejemplo, podrías usar la función uniqid() de PHP para generar IDs únicos al menos para la sesión actual. Una vez generado, este ID debe incluirse 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;

?>

Añadir etiquetas #

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

Recomendamos usar etiquetas que describan la página donde se utiliza la llamada y el tipo de resultados que muestra. Un ejemplo podría ser Homepage - Trending. Esto facilita distinguirlas en los 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 en un producto de Clerk.io con el endpoint log/click.

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

La llamada debe contener también el parámetro api, que es el endpoint usado para mostrar el producto clicado, y product con el ID del producto clicado.

Search & Recommendations #

Registrar los clics se realiza añadiendo los parámetros a la llamada según el endpoint usado para mostrar el producto clicado. Es simple ya que utiliza datos de la configuración realizada.

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 #

El registro de clics funciona de manera diferente, ya que recibirás los datos de solicitudes GET reenviadas por Clerk.io. Debes monitorear si la URL incluye parámetros que indican que los visitantes llegan a una página de producto desde un 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, de ser así, registrar el clic con los datos recibidos.

clerk_api contiene el endpoint API con un carácter * para evitar problemas de codificación. Esto debe cambiarse a / al registrar el clic. external: 1 debe añadirse a 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 ven páginas de productos, esto debe ser registrado para que pueda usarse en la personalización de resultados, sobre todo los relacionados con el visitante, como Visitor Recommendations o Visitor Alternatives.

Si usas endpoints que ya necesitan el ID del producto para funcionar, como recommendations/substituting o recommendations/complementary, Clerk.io registrará el ID del producto de forma automática.

Sin embargo, si no usas estos, necesitas hacer una llamada aparte a log/product, con el ID del producto que se está navegando.

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 es clave realizar el seguimiento en tiempo real. El endpoint log/sale se utiliza para esto.

Incluyendo el Visitor ID en esta llamada, Clerk entenderá qué productos fueron mostrados, clicados y finalmente comprados. Esto permite que la IA permanezca siempre actualizada y pueda cambiar los resultados al instante 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, lo que permite una personalización aún mejor a través de recomendaciones específicas para clientes.

El id de los productos debe coincidir con los IDs registrados para los clics. Por ejemplo, para productos configurables debes registrar el ID del producto padre tanto en log/click como en log/sale independientemente de la variante comprada.
El price es el precio unitario. Se multiplicará por la 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.