# Sincronizza i metafield

Questa guida spiega come sincronizzare i metafield dal negozio di origine al negozio di destinazione con l’app Tipo.

### ℹ️ Cosa sono i metafield?

* **Metafield del prodotto**
* **Metafield della variante** (se li abiliti)

L’app Tipo può sincronizzare metafield per:

* materiale, guida alle taglie, specifiche
* badge personalizzati (ad es. “best\_seller”)
* dettagli aggiuntivi del prodotto usati da temi o app

I metafield sono campi personalizzati di Shopify usati per memorizzare dati aggiuntivi dei prodotti, come:

***

### ✅ **Tipi di metafield supportati**

* Testo su più righe
* Testo RTF
* Numero intero
* Decimale
* Data e ora
* Data
* Dimensione
* Volume
* Peso
* Vero o falso
* Valutazione
* URL
* Denaro
* Link
* JSON

🚫 **Non ancora supportati:**\
I tipi di riferimento (ad es. riferimento a prodotto, riferimento a collezione) non sono attualmente supportati.

***

### 🛠️ Passaggio 1: configura i metafield nel negozio di origine

1. Apri l’app > fai clic su **Impostazioni (Settings)** > attiva **Condividi metafield (Share Metafields)**
2. Scegli la risorsa che vuoi condividere:
   * **Risorsa prodotto (Product resource)** – Condivide i metafield dei prodotti.
   * **Risorsa variante (Variant resource)** – Condivide i metafield delle varianti.
3. Aggiungi definizioni di metafield specifiche per limitare quali metafield vengono condivisi.
   * Fai clic sull’icona **Sfoglia metafield (Browse metafields)**, oppure
   * Inserisci la definizione del metafield nel formato:

     ```
     namespace.key
     ```

     Ad esempio:

     ```
     custom.materialseo.titlespecifications.weight
     ```
4. Click **Save** to update the changes

<figure><img src="/media/4360c99527c6a4de655c.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

<figure><img src="/media/7a7d4dfafe848ed0a876.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

***

### 🛠️ Passaggio 2: configura i metafield nel negozio di destinazione

1. Apri l’app > fai clic su **Negozi (Stores)** > fai clic sull’URL del negozio di origine per aprire i dettagli della connessione

<figure><img src="/media/b99e7e334515ad4e086d.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

2. Attiva **Sincronizzazione metafield (Metafields sync)**
3. Scegli cosa sincronizzare

   In **Dati consentiti (Allow data)**, seleziona una o entrambe le opzioni:

   * **Risorsa prodotto** → sincronizza i metafield dei prodotti
   * **Risorsa variante** → sincronizza i metafield delle varianti
4. Fai clic sull’icona di ricerca a destra per vedere tutti i metafield supportati > fai clic sul pulsante **Seleziona metafield validi da sincronizzare (Select valid metafield to sync)**&#x20;

<figure><img src="/media/4360c99527c6a4de655c.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

<figure><img src="/media/7a7d4dfafe848ed0a876.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

5. Fai clic su **Salva** per applicare le modifiche

***

### &#x20;🔄 Cosa succede durante la sincronizzazione

#### **1) Se il negozio di destinazione non ha la definizione del metafield**

L’app crea automaticamente la definizione del metafield nel negozio di destinazione (quando necessario).

Dopo la creazione, i valori dei metafield sincronizzati compariranno sul prodotto o sulla variante nel negozio di destinazione.

#### **2) Se i metafield esistono ma non sono “strutturati” (metafield non strutturati)**

In alcuni casi i metafield possono essere sincronizzati anche se non sono stati definiti o strutturati completamente nel negozio di destinazione.

Per consultarli in Shopify Admin:

* **apri** le **Impostazioni** del negozio **→ Metafield e metaoggetti**
* Scegli **Prodotto** (o **Variante**)
* Apri **Visualizza metafield non strutturati**

💡 Suggerimento: puoi definire o strutturare manualmente questi metafield in un secondo momento per mantenere i dati del negozio puliti e coerenti.

<figure><img src="/media/755ea231da077f6819c8.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

#### **3) Se il negozio di origine non ha alcun valore, la destinazione non viene sovrascritta**

Se un metafield esiste nel negozio di destinazione ma il valore di origine è vuoto, Tipo Sync non sovrascrive il valore di destinazione.

#### **4) I tipi di dati devono corrispondere (molto importante)**

I tipi di dati dei metafield devono corrispondere esattamente tra negozio di origine e negozio di destinazione.

Esempi di tipi di dati non corrispondenti:

* `single_line_text_field` vs `multi_line_text_field`
* `number_integer` vs `number_decimal`
* `product_reference` vs `text`

⚠️ Se i tipi di dati non corrispondono, la sincronizzazione potrebbe non riuscire o saltare quel metafield.

***

### 📌 Esempio: sincronizzare un metafield del prodotto – “Materiale”

Vuoi sincronizzare un **metafield personalizzato del prodotto** chiamato **Materiale** (ad es. “Cotone”, “Pelle”, “Lana”) dal tuo **negozio di origine** al tuo **negozio di destinazione** usando la nostra app.

#### **Passaggio 1: definisci il metafield in Shopify**

Nel tuo **negozio di origine**:

1. Vai a **Shopify Admin >** apri le **Impostazioni** del negozio **> Metafield e metaoggetti** > scegli **Prodotto** (o **Variante**)
2. Fai clic su **Aggiungi definizione** (se non è già stata creata) > compila la definizione del metafield:
   * **Nome**: Materiale
   * **Namespace**: `custom`
   * **Chiave**: `material`
   * **Tipo**: Testo su una sola riga

\=>  Così ottieni la chiave completa del metafield: `custom.material`

Ripeti questo passaggio nel tuo **negozio di destinazione** (chiave e tipo devono essere identici).

<figure><img src="/media/e68676d721f26cb93ef7.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

#### **Passaggio 2: aggiungi i dati dei metafield ai prodotti**

Nel tuo **negozio di origine**, vai a un prodotto e scorri fino a **Metafield**  > in **Materiale**, inserisci: `Cotton`

Ora questo prodotto ha il metafield `custom.material = "Cotton"`.

<figure><img src="/media/97a6ddb98ed50e435682.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

#### **Passaggio 3: configura la sincronizzazione nell’app Tipo**&#x20;

* Apri la nostra app nel **negozio di destinazione** > vai a Configurazione connessione **> Sincronizzazione metafield**
* Scegli **Metafield specifici > i**nserisci esattamente la chiave del metafield: `custom.material`&#x20;

<figure><img src="/media/7a7d4dfafe848ed0a876.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

**Risultato**

* La nostra app troverà `custom.material` nel negozio di origine
* Se **non esiste** nel prodotto di destinazione, l’app lo **creerà**\
  \=>   Risultato: `custom.material = "Cotton"` in entrambi i negozi
* Se esiste nel negozio di destinazione ma quello di origine è vuoto, **non sovrascriviamo** il valore

***

### ❓FAQ

#### D1: come imposto `namespace.key` nel mio negozio?

Per sincronizzare un metafield specifico, devi inserire la **chiave di definizione del metafield** in questo formato: `namespace.key` (ad esempio: `custom.color`).

Ecco come trovarla nel tuo Shopify Admin:

1. Vai al tuo Shopify Admin > vai a **Impostazioni > Dati personalizzati > Prodotti**
2. Fai clic sul metafield che vuoi sincronizzare\
   → Vedrai i valori di **Namespace** e **Chiave**
3. Combinali in questo formato: `namespace.key`\
   → Esempio: `custom.description`

#### D2: perché i miei metafield non vengono sincronizzati?

Se i metafield non vengono sincronizzati correttamente, la causa potrebbe essere una delle seguenti:

1. **La sincronizzazione dei metafield non è abilitata**\
   Assicurati che la sincronizzazione dei metafield sia attiva in entrambi i negozi:
   * Abilita **Condividi metafield** nel **negozio di origine**.
   * Abilita **Ricevi metafield (Receive Metafields)** nel **negozio di destinazione**.

<figure><img src="/media/4360c99527c6a4de655c.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

2. **La chiave di definizione del metafield non è stata aggiunta**

Oltre ad abilitare la sincronizzazione dei metafield, devi anche aggiungere la **chiave di definizione del metafield (namespace.key)** che vuoi sincronizzare.

* Vai a **Impostazioni → Condividi metafield**
* Assicurati che **Abilita (Enable)** sia selezionato
* In **Dati consentiti**, aggiungi la definizione del metafield in questo formato:\
  `namespace.key`\
  Esempio: `custom.material`&#x20;

<figure><img src="/media/f4d2b012b6b982aa41e6.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

3. **Tipi di metafield non supportati**\
   Alcuni tipi di dati dei metafield non sono supportati, come i **tipi di riferimento** o i **metaoggetti**.

Rosso: metafield non supportati che l’app non può sincronizzare

<figure><img src="/media/85f75cd1117f373c78df.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

4. **Tipi di metafield non corrispondenti tra i negozi**\
   Il metafield nel negozio di origine e in quello di destinazione deve avere **lo stesso tipo di dati e la stessa struttura**.\
   Le discrepanze più comuni sono:

* Un metafield è **Testo su una sola riga**, mentre l’altro è **Testo su più righe**.
* Un metafield usa **Valore singolo**, mentre l’altro usa **Elenco di valori**.

Per risolvere questi problemi, verifica che i metafield in entrambi i negozi abbiano lo stesso **namespace**, la stessa **chiave** e lo stesso **tipo di dati**, quindi riprova a sincronizzare.

***

**🙋 Hai ancora bisogno di assistenza?**

Se hai ancora bisogno di aiuto, scrivici pure a <hi@tipo.io>. Saremo felici di aiutarti.
