SDK Go

Le client officiel Go de l’API LIKYLY : envoyez votre catalogue et ce que font vos visiteurs, recevez des recommandations personnalisées.

catalogue → événements → recommandations → impression → clic → achat

Installation

go get github.com/likyly/likyly-go

Go 1.21 ou plus récent. Bibliothèque standard uniquement. Chaque appel prend un context.Context. Utilisable en concurrence.

Démarrage rapide

Les extraits s'exécutent dans func main() ; log.Fatal les garde courts, gérez les erreurs comme vous le souhaitez.

1. Initialiser

Créez un client et réutilisez-le. Utilisez votre clé secrète côté serveur (voir Quelle clé ?).

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/likyly/likyly-go"
)

ctx := context.Background()

// Backend only: the secret key gives access to your catalog and your users.
client, err := likyly.New(os.Getenv("LIKYLY_SECRET_KEY"))
if err != nil {
	log.Fatal(err)
}

2. Envoyer votre catalogue

// Send your catalog once (and whenever it changes). Ids are YOUR ids: SKUs, UUIDs, Shopify gids...
_, err = client.Items.UpsertMany(ctx, []likyly.ItemImport{
	{ItemID: "SKU-1", Title: "Nike Air Max", Description: "Running shoe with air cushioning", Properties: likyly.Properties{"category": "shoes", "brand": "Nike", "price": 129.9}},
	{ItemID: "SKU-2", Title: "Adidas Ultraboost", Description: "Responsive running shoe", Properties: likyly.Properties{"category": "shoes", "brand": "Adidas", "price": 149}},
	{ItemID: "SKU-3", Title: "Nike Pegasus", Description: "Everyday running shoe", Properties: likyly.Properties{"category": "shoes", "brand": "Nike", "price": 119}},
})
if err != nil {
	log.Fatal(err)
}

// Users are optional: describe them if you want the profile to travel with their events.
_, err = client.Users.Upsert(ctx, "user_123", likyly.UserInput{Properties: likyly.Properties{"country": "FR", "segment": "premium"}})
if err != nil {
	log.Fatal(err)
}

Les identifiants sont les vôtres : n’importe quelle chaîne (SKU-123, un UUID, gid://shopify/Product/123). properties est libre ; category et description améliorent la similarité, le reste est stocké tel quel.

3. Suivre les événements

// Tell LIKYLY what your visitors do.
if _, err = client.Events.View(ctx, likyly.EventInput{UserID: "user_123", ItemID: "SKU-1"}); err != nil {
	log.Fatal(err)
}

// Purchases carry an EventID: replaying the call can never count the sale twice.
_, err = client.Events.Purchase(ctx, likyly.EventInput{
	EventID:    "purchase_order_9281_SKU-1",
	UserID:     "user_123",
	ItemID:     "SKU-1",
	Quantity:   1,
	Properties: likyly.Properties{"price": 129.9, "currency": "EUR", "orderId": "order_9281"},
})
if err != nil {
	log.Fatal(err)
}

4. Obtenir des recommandations

// Ask what to show. You never pick an algorithm: LIKYLY chooses the best strategy for what it knows.
recs, err := client.Recommendations.Get(ctx, likyly.RecommendationRequest{UserID: "user_123", Placement: "homepage", Limit: 3})
if err != nil {
	log.Fatal(err)
}

fmt.Println("strategy:", recs.Strategy)
for _, item := range recs.Items {
	fmt.Println(item.ItemID, item.Title)
}

Vous ne choisissez jamais d’algorithme : LIKYLY sélectionne la meilleure stratégie selon ce qu’il sait du visiteur et vous dit laquelle il a utilisée (strategy : hybrid, content, collaborative, session ou popular). Sans utilisateur, sans session et sans article, vous obtenez tout de même une réponse utile : ce qui est populaire.

5. Boucler : l’attribution

// Send the RecommendationID back: LIKYLY measures which recommendations get seen, clicked and bought.
shown := likyly.EventInput{UserID: "user_123", ItemID: recs.Items[0].ItemID, RecommendationID: recs.RecommendationID, Placement: "homepage"}
if _, err = client.Events.Impression(ctx, shown); err != nil {
	log.Fatal(err)
}
if _, err = client.Events.Click(ctx, shown); err != nil {
	log.Fatal(err)
}

Renvoyez l’identifiant de recommandation sur les événements suivants (impression à l’affichage, click, add_to_cart, purchase) : LIKYLY mesure ainsi quelles recommandations convertissent réellement.

Quelle clé ?

La clé publique ne peut que lire des recommandations et écrire des événements : elle peut donc être exposée. Ne mettez jamais la clé secrète dans du code livré à un navigateur ou à une application mobile.

// Where the code is exposed to visitors, use the PUBLIC key: it can only read recommendations and record events.
front, err := likyly.New(os.Getenv("LIKYLY_PUBLIC_KEY"))
if err != nil {
	log.Fatal(err)
}

// A visitor who is not logged in: use an anonymous session id (any string you generate and keep in a cookie).
if _, err = front.Events.View(ctx, likyly.EventInput{SessionID: "sess_abc", ItemID: "SKU-2"}); err != nil {
	log.Fatal(err)
}
forVisitor, err := front.Recommendations.Get(ctx, likyly.RecommendationRequest{SessionID: "sess_abc", ViewedItemIDs: []string{"SKU-2"}, Placement: "product_page", Limit: 3})
if err != nil {
	log.Fatal(err)
}

Événements

track est le mécanisme unique ; impression, view, click, add_to_cart, remove_from_cart et purchase sont des raccourcis vers celui-ci. Les types d’événements sont des chaînes libres : utilisez les vôtres (favorite, share, video_played...) aussi librement que les officiels.

// Any string is a valid event type: track what matters to your business.
_, err = client.Events.Track(ctx, "favorite", likyly.EventInput{UserID: "user_123", ItemID: "SKU-2", Properties: likyly.Properties{"list": "wishlist"}})
if err != nil {
	log.Fatal(err)
}

// Up to 1000 events per call, each with its own type.
_, err = client.Events.TrackMany(ctx, []likyly.TypedEvent{
	{Type: "view", EventInput: likyly.EventInput{UserID: "user_123", ItemID: "SKU-3"}},
	{Type: "add_to_cart", EventInput: likyly.EventInput{UserID: "user_123", ItemID: "SKU-3", Quantity: 1}},
})
if err != nil {
	log.Fatal(err)
}

• Un événement porte un article et un utilisateur, une session, ou les deux (les deux relient la session anonyme à l’utilisateur une fois connecté).
• Visiteurs anonymes : générez un identifiant de session (n’importe quelle chaîne) et gardez-le dans un cookie ; aucune connexion requise.
• properties est un objet libre (prix, devise, numéro de commande...). Ses clés sont stockées telles que vous les envoyez et jamais renommées par le SDK.
• L’identifiant d’événement (clé d’idempotence) : rejouer un événement avec le même identifiant n’enregistre rien et renvoie duplicate: true. Renseignez-le sur les achats, par exemple purchase_<commande>_<article>.
• placement est un libellé libre de l’endroit où quelque chose s’est produit ou sera affiché (homepage, product_page, cart...).

Recommandations avancées

recommendations.get est la voie normale. Pour choisir vous-même la stratégie :

// Advanced Recommendations: one strategy at a time, when you want to choose.
alpha := 0.7
similar, err := client.Recommendations.Similar(ctx, likyly.SimilarOptions{ItemID: "SKU-1", AdvancedOptions: likyly.AdvancedOptions{Limit: 3}})
if err != nil {
	log.Fatal(err)
}
hybrid, err := client.Recommendations.Hybrid(ctx, likyly.HybridOptions{UserID: "user_123", ItemID: "SKU-1", Alpha: &alpha, AdvancedOptions: likyly.AdvancedOptions{Limit: 3}})
if err != nil {
	log.Fatal(err)
}
session, err := client.Recommendations.Session(ctx, likyly.SessionOptions{ViewedItemIDs: []string{"SKU-1", "SKU-2"}, AdvancedOptions: likyly.AdvancedOptions{Limit: 3}})
if err != nil {
	log.Fatal(err)
}

Ces endpoints portent les identifiants dans le chemin de l’URL : un identifiant contenant / (comme gid://shopify/Product/1) ou, pour la liste de session, ,, est refusé par une erreur de validation. Utilisez alors recommendations.get, qui prend les identifiants dans le corps de la requête.

Erreurs

Les erreurs sont typées (toutes sont des error). Interceptez celles qui vous concernent :

Les erreurs issues de l’API portent : StatusCode, RequestID, RetryAfter (time.Duration), Body. Communiquez l’identifiant de requête lorsque vous contactez le support.

_, err = client.Items.Get(ctx, "does-not-exist")
var notFound *likyly.NotFoundError
var rateLimited *likyly.RateLimitError
switch {
case errors.As(err, &notFound):
	fmt.Println("no such item, request", notFound.RequestID)
case errors.As(err, &rateLimited):
	fmt.Println("slow down, retry in", rateLimited.RetryAfter)
case err != nil:
	log.Fatal(err)
}

Tentatives et délais

Le SDK relance pour vous les échecs transitoires (2 tentatives par défaut, backoff exponentiel à partir de 0,5 s plafonné à 8 s, avec jitter complet) :

• 429 : toujours relancé, en respectant Retry-After. Un Retry-After supérieur à 60 s n’est pas attendu : l’erreur de limite de débit est renvoyée.
• 502, 503, 504, connexions coupées et délais dépassés : relancés uniquement quand rejouer l’appel est sans danger : lectures, upserts, suppressions, événements portant un identifiant d’événement, et lots dont chaque événement en a un.
• Un événement sans identifiant d’événement n’est jamais relancé après un échec ambigu : un réseau capricieux ne peut donc jamais enregistrer un achat deux fois. Renseignez l’identifiant sur les événements qui comptent et ils deviennent relançables.
• Les autres erreurs 4xx ne sont jamais relancées.

Configuration

tuned, err := likyly.New(os.Getenv("LIKYLY_SECRET_KEY"),
	likyly.WithTimeout(5*time.Second),                                   // per attempt (default 10s)
	likyly.WithMaxRetries(3),                                            // automatic retries on 429 / 502 / 503 / 504 / network errors (default 2, 0 disables)
	likyly.WithUserAgent("my-shop/1.4"),                                 // appended to the SDK's User-Agent
)
if err != nil {
	log.Fatal(err)
}

Annulation et échéance via le context.Context. Les options par appel viennent en dernier : WithRequestTimeout(d), WithRequestMaxRetries(n).

Référence

Clé : S = clé secrète uniquement, P = clé publique ou secrète.

Les listes sont paginées avec limit et offset (la page par défaut de l’API compte 100 articles) ; le total est fourni avec la page. Les utilisateurs ont un import par lot mais pas de suppression par lot : l’API n’a pas de tel endpoint. L’import des articles est un alias de l’upsert par lot (l’import CSV est une fonction du tableau de bord).

Notes Go

• Les champs optionnels utilisent la valeur zéro comme « non renseigné » (Limit: 0 = valeur par défaut de l'API). HybridOptions.Alpha est un *float64 pour que 0 reste exprimable. Testez les erreurs avec errors.As ; une *ValidationError issue d'un 422 correspond aussi à *APIError.
• Les champs des requêtes et des réponses sont des structs en PascalCase ; les clés de Properties (une map[string]any) vous appartiennent et ne sont jamais renommées.