SDK iOS (Swift)

LIKYLY montre à chaque utilisateur de votre application les produits qu’il a le plus de chances de vouloir : « Vous aimerez aussi » sur une fiche produit, « Recommandé pour vous » sur l’accueil. Il apprend de ce que font vos utilisateurs, simple consultation comprise.

Ce SDK tourne sur le téléphone de vos utilisateurs : il utilise donc la clé publique et couvre ce qu’elle permet. Il demande quoi afficher, signale ce que font les utilisateurs et ce que deviennent les recommandations, et garde un identifiant anonyme sur l’appareil. Votre catalogue, lui, est envoyé depuis votre serveur avec un SDK serveur et la clé secrète.

iOS / iPadOS 15+, macOS 12+, tvOS 15+, watchOS 8+ · Swift 5.9+ (Xcode 15+) · async/await · aucune dépendance

Installation

// Xcode : File › Add Package Dependencies… › https://github.com/likyly/likyly-swift
// ou dans Package.swift :
.package(url: "https://github.com/likyly/likyly-swift", from: "1.0.0")
// cible : .product(name: "Likyly", package: "likyly-swift")

Installation par Swift Package Manager, directement depuis GitHub. Le paquet est aussi référencé sur Swift Package Index.

La clé publique, jamais la clé secrète

Tout ce qui est livré dans une application peut en être extrait. Utilisez la clé publique (pk_…, page Compte, « Clé publique ») : elle ne sait que demander des recommandations et enregistrer des événements. Le SDK refuse une clé secrète (sk_) ou développeur (lk_) dès sa création : l’erreur apparaît tout de suite, au lieu de partir dans une version publiée.

Démarrage rapide

1. Un client et une session pour toute l’application

import Likyly

let likyly = try Likyly(apiKey: "pk_live_xxx")   // la clé PUBLIQUE
let session = LikylySession()                     // identifiant anonyme, gardé dans UserDefaults

2. Afficher un emplacement, et signaler ce qui a été vu et touché

let recs = try await likyly.recommend(
    "pdp-related",                                // emplacement configuré une fois dans LIKYLY
    context: PlacementContext(itemId: "SKU-456", userId: currentUser?.id, sessionId: session.anonymousId),
    limit: 8)

// Une carte devient visible (une fois par carte) :
try await likyly.events.impression(EventInput(itemId: recs.items[0].itemId, sessionId: session.anonymousId,
                                              recommendationId: recs.recommendationId, placement: recs.placement))
// Une carte est touchée :
try await likyly.events.click(EventInput(itemId: recs.items[0].itemId, sessionId: session.anonymousId,
                                         recommendationId: recs.recommendationId, placement: recs.placement))

Un emplacement (pdp-related, home-for-you…) se configure une fois dans LIKYLY, par votre assistant IA ou dans la console. Renvoyez le recommendationId sur l’impression et le clic : LIKYLY apprend quelles recommandations fonctionnent, et vous mesurez ce qu’elles rapportent.

3. Ce que font vos utilisateurs ailleurs dans l’application

try await likyly.events.view(EventInput(itemId: "SKU-456", sessionId: session.anonymousId))
try await likyly.events.addToCart(EventInput(itemId: "SKU-456", sessionId: session.anonymousId, quantity: 1))
// Un achat : eventId garantit qu'une nouvelle tentative ne le compte jamais deux fois
try await likyly.events.purchase(EventInput(itemId: "SKU-456", userId: user.id, eventId: "purchase_\(order.id)_SKU-456",
                                            quantity: 1, properties: ["price": 129.9, "currency": "EUR"]))
try await likyly.events.track("favorite", EventInput(itemId: "SKU-456", userId: user.id)) // vos propres types

La consultation seule est utile : un utilisateur qui n’achète jamais apprend quand même à LIKYLY quels produits vont ensemble, et reçoit des recommandations. Renseignez un eventId sur les achats.

4. À la connexion

try await session.identify(likyly, userId: user.id)   // à la connexion
session.reset()                                       // à la déconnexion

L’historique anonyme de l’appareil compte alors pour le compte de l’utilisateur.

Exemple complet : Un écran SwiftUI complet.

Si LIKYLY ne répond pas

Les réponses des emplacements sont gardées en mémoire une heure : revenir sur un écran ne coûte rien. Après une erreur réseau, un délai dépassé, un 429 ou une erreur 5xx, les appels d’emplacement échouent aussitôt pendant 30 secondes (erreur « en pause ») : l’écran affiche son propre contenu au lieu d’attendre. Les deux se règlent ou se désactivent :

do {
    recs = try await likyly.recommend("home-personalized", context: ctx)
} catch LikylyError.paused {
    showFallback()                                     // vos meilleures ventes, ou rien
}

let likyly = try Likyly(apiKey: "pk_live_xxx", options: LikylyOptions(
    cache: RecommendCacheOptions(ttlSeconds: 600, pauseSeconds: 15)))   // ou cache: nil
await likyly.clearRecommendationCache()

Nouvelles tentatives : 429, 502, 503, 504 et connexions coupées sont relancés avec un délai croissant (un Retry-After jusqu’à 60 s est respecté). Un événement sans eventId n’est jamais relancé après un échec ambigu : il n’est donc jamais enregistré deux fois.

Erreurs

Tout ce qui est levé est une LikylyError :

Configuration

Notes

• Chaque méthode accepte aussi options: RequestOptions(timeout:maxRetries:) pour un seul appel, et respecte l'annulation des tâches (une .task annulée lève CancellationError).
• LikylySession est un identifiant aléatoire stocké dans les UserDefaults de votre app : ce n'est pas l'IDFA et il n'est jamais partagé avec d'autres apps. Aucune demande App Tracking Transparency n'est nécessaire ; déclarez les données « Interactions avec le produit » dans l'étiquette de confidentialité de l'App Store.