Come usare Hallwil Filters

Hallwil Filters aggiunge filtri per collezioni rapidi, ricerca e scoperta prodotti al tuo storefront Shopify. Questa guida ti accompagna dall'installazione all'integrazione live nel tema.

1. Installare e aprire l'app

Installa Hallwil Filters dallo Shopify App Store e approva le autorizzazioni richieste. Apri l'app da Shopify Admin → Apps.

La schermata iniziale mostra lo stato di indicizzazione del catalogo, il piano attuale e una checklist di configurazione. Completa la checklist per preparare il tuo storefront.

  • Installa l'app sul tuo store di sviluppo o produzione.
  • Apri Hallwil Filters dalla barra laterale di Shopify admin.
  • Verifica che l'indicizzazione del catalogo parta automaticamente dopo l'installazione.

2. Indicizzazione del catalogo

L'app indicizza i tuoi prodotti in un motore di ricerca (Typesense) così che filtri e ricerca rispondano in millisecondi. L'indicizzazione avviene in background dopo l'installazione o quando avvii una reindicizzazione.

Durante l'indicizzazione, i conteggi dei filtri possono essere incompleti. Attendi che lo stato mostri Ready nella home page o in Impostazioni.

  • Pending / Indexing — la sincronizzazione del catalogo è in corso.
  • Ready — l'API storefront può restituire dati completi di filtri e prodotti.
  • Error — controlla la connettività Redis e usa Reindex catalog in Impostazioni.

3. Creare set di filtri

Vai a Filters nella navigazione dell'app. Un set di filtri definisce quali filtri appaiono su pagine di collezione o ricerca specifiche.

Aggiungi filtri da opzioni prodotto, vendor, type, tags, prezzo, disponibilità o metafields. Configura i tipi di visualizzazione (checkbox, swatch, range) e l'ordine.

  • Crea un set di filtri e assegna handle di collezione o usalo come predefinito per la ricerca.
  • Aggiungi filtri e associa ciascuno a un attributo prodotto.
  • Anteprima i conteggi delle facet dall'editor del set di filtri quando l'indice è pronto.

4. Integrazione storefront

Il tuo tema chiama la Discovery API tramite Shopify App Proxy su https://{your-store}.myshopify.com/apps/discovery/v1/*. Shopify firma automaticamente ogni richiesta storefront — non aggiungere firma o timestamp nel codice del tema.

Usa l'URL App Proxy mostrato in Impostazioni o nella pagina Documentation dell'app. Endpoint tipici: /v1/filters, /v1/products, /v1/search/suggest.

Per esempi Liquid e JavaScript, apri Documentation nell'app embedded (URL proxy specifico dello store ed esempi di codice).

5. Fatturazione e piani

I piani di abbonamento sono gestiti tramite Shopify Billing. Apri Billing nell'app per visualizzare il piano, effettuare l'upgrade o annullare.

I limiti del piano (set di filtri, mercati, volume di indicizzazione) si applicano secondo il livello mostrato nella pagina Billing.

6. Migrazione e strumenti catalogo

Usa Migration per esportare o importare attributi prodotto allineati ai tuoi filtri (vendor, tags, opzioni, metafields) tramite Excel.

Usa Catalog overview nella home page per ispezionare prodotti indicizzati e copertura delle facet.

7. Supporto e risorse

La Documentation embedded (Shopify admin → Hallwil Filters → Documentation) include esempi API e codice di integrazione tema per il tuo store.

La documentazione OpenAPI interattiva è disponibile sul servizio Discovery API quando è distribuito.

  • Documentation in-app — esempi API e snippet per il tema.
  • Riferimento API (Swagger) — schemi completi di richiesta/risposta.
  • Impostazioni — lingua, reindicizzazione, URL App Proxy, link legali.