Come verificare che Pandectes funzioni con la Customer Privacy API di Shopify

Panoramica

Pandectes GDPR Compliance è integrata con la Customer Privacy API di Shopify. Quando un visitatore sceglie Accept, Reject o una selezione personalizzata nella finestra delle preferenze, il banner comunica quella scelta a Shopify tramite l'API ufficiale. Shopify poi la applica alle superfici che controlla: web pixel, customer events, pubblici e checkout.

Questo articolo mostra come confermare che il segnale arrivi nel tuo negozio. Elenca anche i controlli che sembrano errori ma non lo sono.

Per sapere come si comporta l'integrazione, consulta How the app works with Shopify's Customer Privacy API. Il riferimento ufficiale di Shopify è la Customer Privacy API.

Come funziona

Il compito dell'app in questa integrazione è passare a Shopify la decisione del visitatore, in modo corretto e immediato. Tutto ciò che viene dopo spetta a Shopify: caricare o trattenere i web pixel nel negozio e nel checkout, filtrare i canali di vendita come Google & YouTube o Meta e applicare il consenso a customer events, pubblici e checkout.

Sono sistemi di proprietà di Shopify che leggono il consenso dall'API di Shopify. Una volta che i controlli seguenti mostrano che il segnale arriva, l'app ha fatto ciò che deve fare.

setTrackingConsent() è il modo documentato in cui un'app comunica a Shopify cosa ha deciso un visitatore. Pandectes la richiama. Quella chiamata è l'interfaccia tra l'app e Shopify.

Punti chiave

• Usa currentVisitorConsent() per verificare la decisione effettiva del visitatore ('', 'yes' o 'no').
• I metodi Allowed() combinano impostazioni del commerciante, posizione e consenso. Un true o false da solo non dimostra che il visitatore abbia deciso qualcosa.
• shouldShowBanner() è un controllo sulla regione. Può restare true dopo Accept.
• Non leggere i cookie di Shopify, il dataLayer o le richieste di rete per giudicare questa integrazione.
• Il primo controllo non installa nulla. Lo snippet del tema e il pixel di prova sono temporanei. Rimuovili quando hai finito.

Prima di iniziare

Tre cose, altrimenti i risultati saranno fuorvianti:

1. Usa un profilo del browser pulito. Apri una nuova finestra in incognito / privata, oppure cancella cookie e local storage per il tuo dominio. Se hai già dato il consenso, il banner non verrà richiesto di nuovo e vedrai solo lo stato "dopo".
2. Esegui il test come visitatore di una regione in cui il consenso è richiesto (ad esempio SEE/UE/Regno Unito, se il tuo banner è configurato così). Nelle regioni in cui Shopify non è configurato per richiedere il consenso, tutto è consentito per impostazione predefinita e il test non dimostra nulla.
3. Assicurati che l'app embed di Pandectes sia attivata nel tuo tema. L'integrazione Shopify Customer Privacy è sempre attiva e non ha alcuna impostazione da attivare.

Apri la Developer Console del browser:

• Chrome / Edge: premi F12, poi apri la scheda Console
• Firefox: premi F12, poi apri la scheda Console
• Safari: attiva il menu Develop in Settings → Advanced, poi Option + Command + C

Cosa invia Pandectes a Shopify

L'API di Shopify usa quattro finalità. Pandectes mappa le proprie categorie di cookie su di esse:

I cookie strettamente necessari non hanno un equivalente. Sono sempre consentiti e non fanno parte di questa scrittura del consenso.

Opzione 1: Quick Console Check

Non devi installare nulla. Basta un comando, eseguito tre volte.

Passaggio 1. Apri il tuo negozio in una nuova finestra in incognito. Compare il banner. Non fare clic su nulla.

Passaggio 2. Apri la Console, incolla questo e premi Invio:

window.Shopify.customerPrivacy.currentVisitorConsent();

Dovresti ottenere quattro stringhe vuote. È il modo in cui Shopify dice che il visitatore non ha ancora deciso:

{marketing: '', analytics: '', preferences: '', sale_of_data: ''}

Passaggio 3. Fai clic su Accept all nel banner, poi esegui di nuovo lo stesso comando:

{marketing: 'yes', analytics: 'yes', preferences: 'yes', sale_of_data: ''}

Passaggio 4. Ricarica la pagina ed eseguilo un'ultima volta. I valori devono essere ancora presenti.

Vuoti prima della decisione, compilati subito dopo, ancora compilati al caricamento successivo della pagina. Questa è la verifica. Se invece fai clic su Reject all, ottieni 'no' al posto di 'yes'. È altrettanto corretto: al visitatore è stato chiesto e ha detto di no.

Devono cambiare solo preferences, analytics e marketing. sale_of_data può restare vuoto. È normale. Vedi la nota in Cosa non usare per la verifica.

window.Shopify.loadFeatures([{name: 'consent-tracking-api', version: '0.1'}], () => {});

Perché currentVisitorConsent e non marketingAllowed

I commercianti spesso controllano solo questo:

window.Shopify.customerPrivacy.preferencesProcessingAllowed();  // true / false

Questo metodo è utile, ma può rispondere solo true o false. La documentazione di Shopify spiega che questi metodi combinano impostazioni del commerciante, posizione dell'utente e consenso dell'utente.

Quindi false potrebbe significare che il visitatore ha rifiutato, oppure che si trova in una regione in cui il consenso è richiesto e non ha ancora risposto. true potrebbe significare che il visitatore ha accettato, oppure che quella regione non richiede il consenso. Il solo valore booleano non può dirti se il visitatore abbia deciso qualcosa.

currentVisitorConsent() restituisce le preferenze selezionate dall'utente e non mescola posizione o configurazione del commerciante:

window.Shopify.customerPrivacy.currentVisitorConsent();
// → {marketing: 'yes', analytics: 'no', preferences: 'yes', sale_of_data: ''}

Vuoto prima che il visitatore decida, compilato dopo. Questa transizione è la prova che Pandectes ha scritto la decisione in Shopify.

Opzione 2: On-Screen Theme Test

Questo snippet automatizza il Quick Console Check. Stampa lo stato del consenso nella console al caricamento della pagina e di nuovo quando il visitatore decide. Legge e registra soltanto. Non modifica nulla.

Dove incollare lo snippet del tema

1. Amministrazione di Shopify → Online Store → Themes
2. Sul tuo tema live fai clic su … → Edit code (più sicuro: prima Duplicate il tema e testa sulla copia)
3. Apri layout/theme.liquid
4. Incolla lo snippet subito prima del tag di chiusura </body>
5. Save

{% comment %} PANDECTES CONSENT CHECK: temporary, remove after testing {% endcomment %}
<script>
(function () {
  var pandectesTag = '[Pandectes theme check]';

  function pandectesSnapshot(label) {
    var cp = window.Shopify && window.Shopify.customerPrivacy;
    if (!cp) {
      console.warn(pandectesTag, label, 'API not available');
      return;
    }

    var consent = cp.currentVisitorConsent();

    console.log('%c' + pandectesTag + ' ' + label, 'font-weight:bold;color:#0a7');
    console.table({
      'currentVisitorConsent().preferences' : consent.preferences,
      'currentVisitorConsent().analytics'   : consent.analytics,
      'currentVisitorConsent().marketing'   : consent.marketing,
      'currentVisitorConsent().sale_of_data': consent.sale_of_data,
      'preferencesProcessingAllowed()'      : cp.preferencesProcessingAllowed(),
      'analyticsProcessingAllowed()'        : cp.analyticsProcessingAllowed(),
      'marketingAllowed()'                  : cp.marketingAllowed(),
      'saleOfDataAllowed()'                 : cp.saleOfDataAllowed()
    });
  }

  document.addEventListener('visitorConsentCollected', function (event) {
    console.log(pandectesTag, 'visitorConsentCollected →', event.detail);
    pandectesSnapshot('AFTER the visitor decided');
  });

  (function pandectesWaitForShopify(tries) {
    tries = tries || 0;
    if (window.Shopify && window.Shopify.loadFeatures) {
      window.Shopify.loadFeatures(
        [{ name: 'consent-tracking-api', version: '0.1' }],
        function (error) {
          if (error) {
            console.error(pandectesTag, 'could not load the Customer Privacy API', error);
            return;
          }
          pandectesSnapshot('ON PAGE LOAD');
        }
      );
      return;
    }
    if (tries > 100) {
      console.error(pandectesTag, 'window.Shopify.loadFeatures never became available');
      return;
    }
    setTimeout(function () { pandectesWaitForShopify(tries + 1); }, 100);
  })();
})();
</script>

Come eseguire il test del tema

Apri il tuo negozio in una nuova finestra in incognito, apri la Console e segui questi tre passaggi.

Passaggio 1: prima di toccare il banner

Il banner è sullo schermo. Non hai fatto clic su nulla. Cerca la tabella ON PAGE LOAD.

Le stringhe vuote sono la parte importante. Shopify sta dicendo che questo visitatore non ha ancora deciso.

Passaggio 2: fai clic su un pulsante del banner

Fai clic su Accept all. Due cose devono comparire subito nella console:

1. Una riga visitorConsentCollected → {marketingAllowed: true, saleOfDataAllowed: …, analyticsAllowed: true, preferencesAllowed: true}
2. Una seconda tabella, AFTER the visitor decided:

Se invece fai clic su Reject all, i valori diventano "no" e i metodi Allowed() restano false. "no" non equivale a "": al visitatore è stato chiesto e ha detto di no.

Passaggio 3: ricarica la pagina

Ricarica e guarda la nuova tabella ON PAGE LOAD. I valori del Passaggio 2 devono essere ancora presenti. Questo dimostra che Shopify ha memorizzato la decisione e la restituisce nelle pagine successive.

Se i Passaggi 1, 2 e 3 si comportano come descritto, l'integrazione sta scrivendo il consenso in Shopify.

Opzione 3: Shopify Pixel Test

Lo snippet del tema dimostra che Shopify ha registrato la decisione. Questo secondo snippet dimostra che la decisione raggiunge i web pixel di Shopify (Google & YouTube, Meta, Klaviyo e qualsiasi pixel personalizzato).

I pixel vengono eseguiti in una sandbox, separata dal tuo tema. Shopify passa loro direttamente lo stato del consenso. Lo snippet crea un piccolo pixel di prova che riporta ciò che gli è stato passato.

Dove incollare lo snippet del pixel

1. Amministrazione di Shopify → Settings → Customer events
2. Fai clic su Add custom pixel, chiamalo Pandectes consent check
3. In Customer privacy, imposta Permission su Not required, così questo pixel di prova viene sempre eseguito e può riportare anche lo stato "prima"
4. Incolla il codice, fai clic su Save, poi su Connect

// Pandectes consent check. TEMPORARY test pixel. Disconnect and delete when finished.
const pandectesTag = '[Pandectes pixel check]';

function pandectesLog(label, cp) {
  console.log(pandectesTag + ' ' + label, {
    preferencesProcessingAllowed: cp.preferencesProcessingAllowed,
    analyticsProcessingAllowed:   cp.analyticsProcessingAllowed,
    marketingAllowed:             cp.marketingAllowed,
    saleOfDataAllowed:            cp.saleOfDataAllowed
  });
}

let pandectesConsentState = init.customerPrivacy;
pandectesLog('state when the pixel started', pandectesConsentState);

api.customerPrivacy.subscribe('visitorConsentCollected', (event) => {
  pandectesConsentState = event.customerPrivacy;
  pandectesLog('state after the visitor decided', pandectesConsentState);
});

analytics.subscribe('page_viewed', (event) => {
  pandectesLog('state at page_viewed', pandectesConsentState);
});

Cosa dovresti vedere nel test del pixel

Di nuovo in una finestra in incognito nuova e con la console aperta:

saleOfDataAllowed non fa parte di questo controllo. Fuori dalle regioni con un opt-out dalla vendita dei dati può essere true fin dall'inizio. È previsto.

Se quei tre valori passano da false a true quando fai clic su Accept, Shopify sta passando lo stato del consenso ai pixel.

Una volta che il segnale arriva, il resto spetta a Shopify

I web pixel di Shopify vengono eseguiti in iframe cross-origin isolati in una sandbox, controllati da Shopify. Nessuna app di consenso può avviarli, fermarli o cambiare ciò che inviano. La leva che esiste è il segnale di consenso.

La verifica si divide in due:

1. Il segnale arriva? A questo rispondono i controlli sopra. È la parte di cui è responsabile Pandectes.
2. Shopify agisce in base al segnale? È una questione di Shopify, a cui si risponde nelle impostazioni di Shopify e, se necessario, tramite il supporto di Shopify.

Se currentVisitorConsent() passa da vuoto a 'yes' o 'no' quando il visitatore fa clic, l'app ha fatto il suo lavoro. Se dopo di ciò un pixel o un canale continua a comportarsi in modo inatteso, guarda dal lato di Shopify:

• Settings → Customer events: ogni pixel ha la propria impostazione Customer privacy → Permission. Un pixel impostato su Not required verrà eseguito a prescindere dal consenso, perché è ciò che il negozio ha detto a Shopify di fare.
• La configurazione di ogni canale di vendita. Il canale Google & YouTube, ad esempio, costruisce il proprio segnale di consenso Google a partire dall'API di Shopify. Quella traduzione è codice di Shopify.
• Il supporto di Shopify, per tutto ciò che rimane dopo che l'API contiene il valore corretto.

Pensala come un interruttore della luce: Pandectes è l'interruttore, Shopify è l'impianto elettrico e le lampade. Una volta verificato che l'interruttore scatta, una lampada che resta accesa è una questione di impianto.

Negozi headless e personalizzati

Valgono la stessa API, gli stessi metodi e lo stesso significato di '', 'yes' e 'no' anche su un negozio headless. Il Quick Console Check funziona senza modifiche. Cambia il modo in cui esegui i due snippet, più un'impostazione aggiuntiva.

Non hai un theme.liquid

Le pagine del tuo negozio sono codice tuo, quindi non c'è un posto dove incollare lo snippet del tema così com'è. Due opzioni:

Opzione A: incollalo nella console del browser (nulla da distribuire).
Copia tutto ciò che sta tra <script> e </script> nello snippet del tema, apri il tuo negozio in una finestra in incognito pulita con il banner visibile, incollalo nella Console e premi Invio. Ottieni subito la tabella ON PAGE LOAD e la tabella AFTER the visitor decided quando fai clic sul banner.

Opzione B: inseriscilo nel tuo layout principale.
Aggiungi lo stesso blocco <script> a ciò che viene renderizzato in ogni pagina: il root layout in Hydrogen o Next.js, index.html in un'app Vite/React, e così via. Rimuovilo quando il test è finito.

Lo snippet 2 viene eseguito nel checkout, non nel tuo negozio

I web pixel di Shopify non vengono eseguiti nelle pagine che ospiti tu. Vengono eseguiti sulle superfici di proprietà di Shopify: il checkout e la pagina di stato dell'ordine / di ringraziamento. Per vedere l'output dello snippet del pixel, aggiungi un prodotto al carrello e prosegui verso il checkout con la console aperta. La decisione di consenso presa nel tuo negozio dovrebbe già essere presente quando il pixel parte.

Un'impostazione aggiuntiva: i tuoi due domini

Su un negozio headless, Shopify ha bisogno dei domini del negozio e del checkout prima di poter registrare il consenso. La documentazione di Shopify richiede questi valori per i negozi personalizzati:

• headlessStorefront
• storefrontRootDomain
• checkoutRootDomain
• storefrontAccessToken

Pandectes li invia a ogni scrittura del consenso, a partire dalla configurazione della tua app. Se mancano o sono errati nell'amministrazione di Pandectes, la scrittura in Shopify non può riuscire e currentVisitorConsent() continuerà a restituire stringhe vuote. Se il tuo test headless fallisce, controlla prima questi.

I domini devono inoltre formare una coppia corrispondente: il dominio del negozio e quello del checkout devono appartenere allo stesso negozio, in modo che la decisione presa nel negozio sia quella che vede il checkout.

Cosa non usare per la verifica

Questi controlli misurano altro oppure non fanno parte dell'API documentata.

Non aspettarti che shouldShowBanner diventi false dopo il consenso

Molti commercianti si aspettano che shouldShowBanner() sia true prima del consenso e false dopo, e segnalano un bug quando resta true.

Non è un metodo di consenso. Shopify lo documenta come indicatore del fatto che il cliente attuale si trovi in una regione configurata per mostrare un banner dei cookie. Un visitatore tedesco si trova ancora in Germania dopo Accept, quindi la risposta resta true. Uno shouldShowBanner() che resta true dopo il consenso è previsto.

Lo stesso vale per saleOfDataRegion(), che indica se il cliente attuale si trova in una regione configurata per gli opt-out dalla vendita dei dati. Anche questo è un controllo sulla regione.

Non fare affidamento su getTrackingConsent, getRegulation o isRegulationEnforced

Non compaiono nella documentazione della Customer Privacy API di Shopify. Sono valori interni che Shopify può cambiare o rimuovere. In particolare, getTrackingConsent() che restituisce "yes" prima del consenso non è la prova che sia stato concesso qualcosa.

Non usare userCanBeTracked o userDataCanBeSold

Esistono, ma Shopify li elenca nella documentazione legacy e dice di non iniziare nuove integrazioni con essi. Usa invece currentVisitorConsent() e i quattro metodi Allowed().

Non cercare un cookie _tracking_consent in document.cookie

La documentazione di Shopify dice di non leggere né modificare direttamente i cookie di Shopify. Shopify non promette che il suo cookie di consenso sia leggibile da JavaScript, che abbia un nome particolare o che esista in una determinata release. Non trovarlo non dimostra nulla.

Non giudicare l'app in base al fatto che un pixel o una richiesta di rete venga ancora attivato

Una richiesta che esce dal browser è un risultato di Shopify. Se il segnale di consenso è corretto e un pixel di Shopify viene comunque attivato, a Shopify è stata comunicata la cosa giusta e ha scelto di eseguire il pixel, di solito perché il Permission di quel pixel è Not required in Settings → Customer events, oppure perché il canale di vendita è configurato per funzionare senza consenso. Correggilo lì.

Non confrontare le voci in window.dataLayer

Il dataLayer è Google Consent Mode, un sistema separato dalla Shopify Customer Privacy API. Pandectes scrive in entrambi e anche il canale Google & YouTube di Shopify scrive le proprie voci. Più voci consent in quel punto sono normali e non verificano l'API di Shopify.

Non aspettarti una chiamata setTrackingConsent a ogni caricamento di pagina

Pandectes scrive in Shopify solo quando lo stato cambia. Se Shopify contiene già la stessa decisione, l'app non la invia di nuovo. Dopo un ricaricamento successivo al consenso, dovresti vedere i valori memorizzati ma nessuna nuova scrittura.

Non preoccuparti se sale_of_data resta vuoto

sale_of_data è rilevante dove si applica un opt-out dalla vendita dei dati (principalmente in alcuni stati degli USA). Se il visitatore non si trova in una regione di questo tipo, oppure Do not sell my data non è attivato in Pandectes, questo campo viene escluso da ciò che Pandectes invia. Un sale_of_data vuoto per un visitatore dell'UE è previsto.

Riferimento rapido: i metodi documentati

Se il test fallisce davvero

Per prima cosa stabilisci quale metà è fallita.

Se il segnale è corretto, cioè currentVisitorConsent() passa da vuoto a 'yes' o 'no' quando fai clic, allora l'app sta scrivendo il consenso. Tutto il resto compete a Shopify. Controlla il Permission di ogni pixel in Settings → Customer events, poi la configurazione dei canali di vendita, poi il supporto di Shopify.

Se il segnale manca, cioè currentVisitorConsent() restituisce ancora stringhe vuote dopo aver fatto clic su un pulsante del banner, controlla in quest'ordine:

1. L'app embed di Pandectes è attivata nel tema che stai testando (Online Store → Themes → Customize → App embeds).
2. Stai testando il tema live, non l'anteprima di un altro tema.
3. Non è installata nessun'altra app di consenso. Due app di consenso che scrivono nella stessa API entrano in conflitto. Ne può essere attiva solo una.
4. Non ti trovi in una sessione di anteprima dell'amministrazione, che può comportarsi in modo diverso da una visita reale.
5. Solo per i negozi headless: il dominio del negozio, il dominio del checkout e lo storefront access token sono compilati correttamente nell'amministrazione di Pandectes.

Continua a non funzionare? Contatta [email protected] e includi:

• il dominio del tuo negozio (e, per headless, i domini del tuo negozio e del checkout)
• il paese da cui hai eseguito il test
• l'output della console del Quick Console Check o dello snippet del tema, nei tre momenti (prima del clic / dopo il clic / dopo il ricaricamento)

Pulizia al termine

Non saltare questo passaggio. Il Quick Console Check non installa nulla. Entrambi gli snippet sono temporanei.

1. Snippet del tema: apri layout/theme.liquid, elimina il blocco che inizia con {% comment %} PANDECTES CONSENT CHECK e usa Save. Se hai testato su un tema duplicato, puoi eliminare quella copia del tema.
2. Snippet del pixel: vai su Settings → Customer events, apri Pandectes consent check, usa Disconnect, poi Delete.
3. Negozi headless: se hai aggiunto lo script al tuo layout, rimuovilo e ridistribuisci. Se hai usato la console del browser, basta chiudere la scheda.

Perché è importante:

• Lo snippet del tema stampa i dettagli del consenso nella console di ogni visitatore, in ogni pagina, finché non lo rimuovi.
• Il pixel di prova è configurato con Permission: Not required, quindi viene eseguito prima del consenso per progettazione. Va bene per un breve test e non va bene per un negozio live.
• Entrambi aggiungono lavoro a ogni caricamento di pagina senza alcun vantaggio una volta terminata la verifica.

Rimuoverli non cambia l'integrazione. L'app continua a comunicare il consenso a Shopify come prima.

Riepilogo

Verifica questa integrazione con currentVisitorConsent(). Stringhe vuote prima di una scelta, 'yes' o 'no' subito dopo e gli stessi valori dopo il ricaricamento significano che Pandectes ha scritto la decisione in Shopify. Il caricamento dei pixel, i canali di vendita e il comportamento del checkout da quel momento in poi sono responsabilità di Shopify. Rimuovi gli eventuali snippet temporanei del tema o del pixel quando hai finito.

Aggiornato il: 20/10/2026