Migrazione della piattaforma

Spostare il tuo webshop da una piattaforma a un’altra — ad esempio, da Magento 2 a Shopify, o da WooCommerce a BigCommerce — comporta più che la semplice reinstallazione dell’estensione Clerk.io.

Molto probabilmente gli ID dei tuoi prodotti cambieranno. Il tuo metodo di sincronizzazione dovrà essere modificato. I tuoi design potrebbero fare riferimento a nomi di attributi specifici della piattaforma. E i tuoi dati storici di ordini dovranno essere trasferiti per mantenere l’AI performante fin dal primo giorno.

Questa guida illustra ogni passaggio.

Prima di iniziare #

Prima di modificare qualsiasi cosa in Clerk.io, rispondi a queste due domande:

Gli ID dei tuoi prodotti cambieranno?
La maggior parte delle migrazioni di piattaforma assegna nuovi ID ai prodotti. Questo è importante perché l’AI di Clerk.io collega i prodotti agli ordini usando il campo id. Se gli ID cambiano, gli ordini precedenti faranno riferimento a ID che non esistono più nel nuovo catalogo.

Puoi abbinare gli ID dei prodotti alla cronologia degli ordini?
Se puoi mappare i vecchi ID dei prodotti ai nuovi (o mantenerli completamente), puoi conservare lo Store Clerk.io esistente — indipendentemente dal fatto che cambi il dominio. La cronologia degli ordini dello Store rimane intatta e l’AI conserva le associazioni apprese.

Se non è possibile la mappatura degli ID e non puoi riconciliare i vecchi ordini con i nuovi prodotti, crea un nuovo Store in my.clerk.io e ricomincia da zero. Il dominio stesso non è il fattore decisivo.

1. Mappa gli ID #

Questo è il passaggio più importante. Se la tua nuova piattaforma assegna nuovi ID prodotto, devi decidere come gestire la mancata corrispondenza tra vecchi ordini e nuovi prodotti.

Ci sono due approcci:

Opzione A — Mantieni i vecchi ID
Configura la sincronizzazione della nuova piattaforma per inviare gli stessi valori id utilizzati sulla vecchia piattaforma. Molte piattaforme consentono di includere un campo ID legacy o esterno nel feed dei dati.

Invia l’ID prodotto della vecchia piattaforma come id nel feed Clerk.io o nelle chiamate CRUD API. In questo modo, la cronologia degli ordini esistente corrisponderà ancora correttamente al nuovo catalogo.

Opzione B — Rimappa e ricarica gli ordini
Se non puoi mantenere gli ID, dovrai costruire tu stesso una tabella di mappatura — esternamente a Clerk.io — che traduca i vecchi ID dei prodotti in quelli nuovi. Una volta creata la mappa, ricarichi gli ordini storici con gli ID corretti.

Clerk.io non esegue la mappatura per te. Il tuo sviluppatore produce un set corretto di dati ordini, e tu lo carichi.

Costruire la tabella di mappatura
L’approccio più semplice è usare l’SKU del prodotto come ponte. Gli SKU quasi sempre restano invariati durante la migrazione di piattaforma, anche se cambiano gli ID interni del database.

Il processo è il seguente:

1. Esporta tutti gli ordini dalla vecchia piattaforma, assicurandoti che ogni riga d’ordine contenga il vecchio ID del prodotto e il suo SKU.
2. Interroga il database della nuova piattaforma per trovare ogni prodotto tramite SKU e recuperare il nuovo ID.
3. Sostituisci i vecchi ID con i nuovi ID nei dati degli ordini.

Un esempio semplice in pseudocodice:

for order in old_orders:
    for line in order.products:
        new_id = new_platform.find_product_by_sku(line.sku).id
        line.product_id = new_id

Il risultato è un elenco corretto di ordini in cui ogni riferimento prodotto utilizza gli ID della nuova piattaforma.

Caricamento degli ordini corretti
Una volta completata la mappa, carica gli ordini corretti su Clerk.io. Ci sono due modi per farlo:

Tramite la CRUD API:

POST https://api.clerk.io/v2/order/add

{
  "key": "your_public_api_key",
  "orders": [
    {
      "id": 5001,
      "products": [901, 902],
      "time": 1622548800,
      "email": "luke@skywalker.com"
    }
  ]
}

Oppure tramite un feed dati JSON che include tutto l’array degli ordini corretti. L’importatore lo elaborerà al prossimo ciclo di sincronizzazione. Questa è spesso l’opzione più semplice per grandi volumi di ordini storici.

In ogni caso, 901 e 902 sono gli ID prodotto della nuova piattaforma — non quelli vecchi.

2. Cambia sincronizzazione #

Una volta definita la strategia sugli ID, aggiorna il metodo di sincronizzazione in Clerk.io puntando alla nuova piattaforma.

1. Vai su Data > Configuration in my.clerk.io.
2. Cambia il metodo di sincronizzazione impostandolo sull’integrazione o URL feed della nuova piattaforma.
3. Verifica gli switch Import — assicurati che Product, Categories e Orders siano tutti abilitati.
4. Aggiorna la tua lista di IP consentiti se la nuova piattaforma ha un IP server diverso.
5. Clicca su Start New Data Sync e monitora il log della sincronizzazione.

Dopo il completamento, verifica in Data > Health che il conteggio prodotti e il volume ordini siano corretti.

Se la nuova piattaforma lo supporta, configura aggiornamenti in tempo reale tramite l’estensione della piattaforma o la CRUD API così che nuovi prodotti e ordini vengano inviati a Clerk.io non appena creati — e non solo nel prossimo sync programmato.

3. Aggiorna i design #

I design fanno riferimento agli attributi prodotto usando la sintassi {{ product.attribute_name }}. Se la tua nuova piattaforma usa nomi diversi, quei riferimenti si romperanno o resteranno vuoti.

Ad esempio, un setup Magento 2 potrebbe sincronizzare un attributo personalizzato chiamato {{ product.manufacturer }}, mentre Shopify invia gli stessi dati come {{ product.vendor }}. Ogni design che usa il vecchio nome dovrà essere aggiornato.

Trovare i design interessati:
Usa il campo di ricerca nella pagina Designs. Cerca il vecchio nome dell’attributo — la ricerca analizza tutto l’HTML e il CSS dei design, così puoi trovare ogni design che lo usa.

Aggiornare il riferimento:
Apri ogni design interessato e sostituisci il vecchio nome dell’attributo con quello nuovo.

Usare invece i Modifiers:
Se vuoi evitare di modificare molti design, usa i Modifiers per creare in Clerk.io un attributo stabile che mappi qualunque sia il nome inviato dalla nuova piattaforma.

Per esempio, crea un modifier che copia l’attributo vendor in un nuovo attributo chiamato manufacturer. I tuoi design esistenti continueranno a funzionare senza modifiche:

Create new attribute: manufacturer
Value: {vendor}

Questo è l’approccio meno rischioso per setup complessi con molti design.

4. Continuità degli ordini #

Clerk.io memorizza gli ordini in modo indipendente dal catalogo prodotti. Gli ordini registrati non vengono mai eliminati se i prodotti vengono rimossi dal sync o dal feed — rimangono come record storici e continuano a influenzare l’AI.

Passando di piattaforma, ciò significa:

• Gli ordini registrati con i vecchi ID prodotto restano nello Store.
• I nuovi ordini registrati con i nuovi ID prodotto iniziano ad accumularsi.
• Fino a quando non ci sono abbastanza nuovi ordini, potresti vedere una qualità di personalizzazione ridotta per logiche come Visitor Recommendations e Best Cross-Sell Products.

Per accelerare i risultati, reimporta i tuoi ordini storici con i nuovi ID prodotto (vedi Step 1, Opzione B). Così l’AI avrà un quadro completo già dal primo giorno invece di ripartire da zero.

Se il volume ordini è elevato, dai priorità agli ultimi 12–24 mesi di ordini. Il comportamento d’acquisto recente ha maggior peso per l’AI rispetto ai dati meno recenti.

5. Verifica il tracking #

Dopo il passaggio alla nuova piattaforma, assicurati che il monitoraggio delle vendite funzioni capillarmente.

Controlla quanto segue:

1. La chiamata log/sale viene inviata sulla pagina di conferma ordine con i nuovi ID prodotto.
2. Gli ordini compaiono in Data > Orders con ID prodotto corrispondenti al nuovo catalogo.
3. Data > Health mostra verde per Sales tracking e Clerk sales.

Se il tracking non funziona, l’attribuzione click-to-purchase non sarà operativa e i report sull’impatto sulle vendite saranno incompleti. La Guida al Sales Tracking mostra come configurarlo e fare debug.

Esempio passo dopo passo #

Ecco come appare una migrazione completa da Magento 2 a Shopify.

Prima della migrazione (Magento 2):

• Prodotti sincronizzati con entity ID di Magento (es. id: 4521)
• I design usano {{ product.manufacturer }} per la marca
• Ordini tracciati tramite l’estensione Magento

Step 1 — Mapping ID:
Esporta tutti gli ordini storici da Magento con ID prodotto e SKU. Interroga Shopify per trovare ogni prodotto tramite SKU e recuperare il nuovo ID Shopify. Sostituisci i vecchi ID nei dati ordine, poi carica gli ordini corretti su Clerk.io tramite CRUD API o feed JSON.

Step 2 — Cambia sync:
In Data > Configuration, modifica il metodo di sincronizzazione passando da Magento 2 all’integrazione Shopify. Esegui una sincronizzazione completa.

Step 3 — Correggi i design:
Cerca nei design manufacturer. Sostituiscilo con {{ product.vendor }} (campo di Shopify), oppure aggiungi un Modifier che mappa vendor → manufacturer per non dover modificare i design.

Step 4 — Verifica:
Effettua un ordine di test sul nuovo store Shopify. Controlla che compaia in Data > Orders con i corretti ID prodotto Shopify. Controlla Data > Health per le spie verdi.

L’intero processo di solito richiede poche ore per migrazioni semplici, e uno o due giorni per grandi cataloghi dove serve rimappare storici ordini.