solidus_meta 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a184b34b3cc96543d01321991267b34e00f9e4f70e9525842dd656fc5aa243e4
-  data.tar.gz: 1be9681add46e69481edd0868f79fa77f4bb7c2e5bb585406536f305b71fd270
+  metadata.gz: 14bb27e1abde5b941ef688e94da4a4b8649d96eca6fc89a5c85425ee6641b6b8
+  data.tar.gz: 76c4b9d5798e65d063ef2047837f629647c3865fb513e23f986794e0c755daf2
 SHA512:
-  metadata.gz: a62b7241a870ba49481770ac8185f72dfb132073ec6de3ebcb56ee448383704646398a17d74e15512058670ef5ab4158488cb5bbb0b9cd7d16e8b264bd47713e
-  data.tar.gz: 23cf1fff325b7cd284afbdf408895954212979b8ded7d7053b4f1eb0a9d952ec3b03161a545a8bf240ef1dd3f8cce9fe7162552a05eacf9eaf014ff2e7d7aad5
+  metadata.gz: 6ba7f2f85a1fedb47d3fcb66da1b3190f6d210315c922888b50147418c8490292ef990ffcc814719e000f13f6907c8c9f56710dd29383a730839c60f8b638fe4
+  data.tar.gz: 896b524d0088eeae20c0364743b8f3afda163f465129abbefbbed7a823e768cd09aaf6a113ff3926cc4047a692ce385d35597d1f49399241855eb711480c4024

data/README.md

@@ -1,6 +1,17 @@
 # SolidusMeta
 
-Envia eventos da [Conversions API da Meta](https://developers.facebook.com/docs/marketing-api/conversions-api) a partir de pedidos do Solidus: `AddToCart`, `InitiateCheckout`, `AddPaymentInfo` e `Purchase`.
+Envia eventos para a Meta a partir de uma loja Solidus, pela [Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api) (servidor) e pelo Pixel (navegador): `ViewContent`, `AddToCart`, `InitiateCheckout`, `AddPaymentInfo`, `Purchase`, `CompleteRegistration` e `Search`.
+
+## Por que enviar pelo navegador e pelo servidor
+
+Cada lado tem informações que o outro não tem, e a Meta atribui melhor as conversões quando recebe os dois:
+
+- **Navegador (Pixel):** roda no navegador do cliente e fala direto com a Meta, que reconhece a pessoa pela sessão do Facebook/Instagram, principalmente no navegador interno desses apps, de onde vem boa parte do tráfego de anúncio no celular. Também identifica visitantes anônimos, que ainda não informaram email ou telefone.
+- **Servidor (Conversions API):** tem os dados do pedido (email, telefone, endereço), não é afetado por bloqueador de anúncio nem pelos limites de cookie do Safari, e envia mesmo quando o cliente já saiu da página, como num PIX confirmado depois por um job.
+
+Os dois são enviados com o mesmo `event_id`, então a Meta junta os dois numa conversão só, sem contar duas vezes. Isso só funciona dentro de 48 horas entre um envio e outro, por isso o `Purchase` no navegador só dispara para pedidos completados no último dia.
+
+No Gerenciador de Eventos, a "cobertura de eventos" mede a parte dos eventos que chega pelos dois lados, e a cobertura de `event_id` mede quantos deles podem ser desduplicados. A Meta recomenda ao menos 75%.
 
 ## Instalação
 
@@ -18,14 +29,30 @@ SolidusMeta.configure do |config|
   config.pixel_id = ENV["META_PIXEL_ID"]
   config.access_token = ENV["META_ACCESS_TOKEN"]
   config.store_url = "https://minhaloja.com.br"
+  config.external_id = ->(order) { order.user_id&.to_s || order.guest_token }
 end
 ```
 
+`external_id` identifica o cliente entre eventos. O padrão é o id do usuário ou o `guest_token` do pedido. Use um valor que o navegador também conheça, para o pixel enviar o mesmo id. Valores que já são um SHA-256 (64 caracteres hexadecimais) são enviados como estão, sem hash de novo.
+
 `store_url` é usado para montar o `event_source_url` de cada evento. Se não for configurado, usa a url da loja do pedido (`order.store.url`). Quando a url vem sem protocolo, a gem adiciona `https://`.
 
 ## Pixel
 
-A gem envia os eventos pelo servidor, mas o pixel da Meta também precisa estar instalado no `<head>` do `app/views/layouts/application.html.erb`. É ele que cria os cookies `_fbp` e `_fbc`, que a gem envia junto de cada evento para a Meta conseguir atribuir a conversão ao clique no anúncio.
+O pixel da Meta precisa estar no `<head>` do layout. Ele cria os cookies `_fbp` e `_fbc`, que a gem envia junto de cada evento. Passe os dados do cliente no `init` (correspondência avançada; o pixel faz o hash):
+
+```erb
+fbq('init', '<%= j ENV["META_PIXEL_ID"] %>', <%= meta_pixel_user_data(order: current_order, user: current_user).to_json.html_safe %>);
+fbq('track', 'PageView');
+```
+
+E, dentro do `<body>`, o tag que dispara no navegador os eventos enviados pelo servidor, com o mesmo `eventID` para a Meta desduplicar:
+
+```erb
+<%= meta_pixel_events_tag %>
+```
+
+Ele precisa ficar no `<body>`: com Turbo, scripts do `<head>` só rodam no carregamento completo da página.
 
 Obs.: O id do pixel precisa estar dessa forma: `<%= j ENV["NOME_DA_ENV"] %>`. Escrever `ENV["NOME_DA_ENV"]` direto no `<script>` não funciona, porque o navegador não tem acesso ao `ENV`.
 
@@ -39,28 +66,42 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-E dispare o `EventJob` nos pontos do fluxo da loja. O `meta_tracking_data` lê os cookies `_fbp` e `_fbc` e, se o app usa [Ahoy](https://github.com/ankane/ahoy), a visita atual, para enviar IP e user agent do cliente:
+O helper também grava o cookie `_fbc` pelo servidor quando a url chega com `fbclid`.
+
+Nos pontos do fluxo da loja, chame `track_meta_event`. Ele enfileira o envio pela Conversions API (com cookies `_fbp`/`_fbc` e IP e user agent da visita do Ahoy ou, sem ela, da requisição) e agenda o mesmo evento, com o mesmo `event_id`, para o pixel disparar na próxima página renderizada:
 
 ```ruby
-SolidusMeta::EventJob.perform_later("AddToCart", line_item_id: line_item.id, quantity:, **meta_tracking_data)
-SolidusMeta::EventJob.perform_later("InitiateCheckout", order_id: order.id, **meta_tracking_data)
-SolidusMeta::EventJob.perform_later("AddPaymentInfo", payment_id: payment.id, **meta_tracking_data)
-SolidusMeta::EventJob.perform_later("Purchase", order_id: order.id, **meta_tracking_data)
+track_meta_event("ViewContent", variant_ids: variants.map(&:id), order_id: current_order&.id)
+track_meta_event("AddToCart", line_item_id: line_item.id, quantity:)
+track_meta_event("InitiateCheckout", order_id: order.id)
+track_meta_event("AddPaymentInfo", payment_id: payment.id)
+track_meta_event("Purchase", order_id: order.id)
+track_meta_event("CompleteRegistration", user:, order_id: current_order&.id)
+track_meta_event("Search", search_string: params[:keywords], content_ids: skus, order_id: current_order&.id)
 ```
 
+Requisições de prefetch do Turbo (`X-Sec-Purpose: prefetch`) não disparam evento.
+
+Na página do pedido, chame `track_meta_purchase_in_browser(order)`. Ele dispara o `Purchase` no navegador para pedidos completados no último dia que ainda não foram disparados nessa sessão, o que cobre pedidos confirmados por job (PIX pago depois).
+
 ### Eventos suportados
 
 | Evento | Quando chamar | Parâmetros |
 |---|---|---|
+| `ViewContent` | Página de produto | `variant_ids:` (variantes que podem ser compradas; a primeira define `value`) e, opcionalmente, `order_id:` |
 | `AddToCart` | Item adicionado ao carrinho | `line_item_id:`, `quantity:` |
 | `InitiateCheckout` | Entrou no checkout | `order_id:` |
 | `AddPaymentInfo` | Pagamento criado com sucesso (PIX gerado, cartão aprovado ou em análise) | `payment_id:` |
 | `Purchase` | Pedido completado (`order.complete` retornou `true`) | `order_id:` |
+| `Search` | Busca feita pelo cliente | `search_string:`, `content_ids:` (SKUs dos primeiros resultados) e, opcionalmente, `order_id:` |
+| `CompleteRegistration` | Conta criada. Conta uma vez por usuário (`event_id` fixo) | `user:` e, opcionalmente, `order_id:` (o carrinho atual, para enviar endereço, telefone e `external_id`) |
+
+Fora de um controller (por exemplo, num job que confirma um pagamento PIX), chame `SolidusMeta::EventJob.perform_later` passando `cookies_meta:` e `ahoy_visit_id:` direto, com os valores salvos durante o checkout.
 
-Fora de um controller (por exemplo, num job que confirma um pagamento PIX), passe `cookies_meta:` e `ahoy_visit_id:` direto, com os valores salvos durante o checkout.
+O `value` é o valor dos produtos com descontos, sem frete. No `AddToCart`, é o preço vezes a quantidade adicionada.
 
 O `event_time` enviado à Meta é o momento em que o job foi enfileirado.
 
 ### Adicionando um evento
 
-Inclua o nome em `SolidusMeta::Event::EVENTS` e crie um método privado em `SolidusMeta::Event` com o nome em snake_case (`ViewContent` → `view_content`). Ele recebe as opções passadas ao job, define `@order` e retorna `path` e, opcionalmente, `event_id`, `fallback` e `custom_data` (que sobrescreve os campos padrão). Sem `event_id`, o id é `<número do pedido>-<event_time>`, então cada disparo conta como um evento separado. Defina um `event_id` fixo quando o evento só pode contar uma vez por pedido, como o `Purchase`.
+Inclua o nome em `SolidusMeta::Event::EVENTS` e crie um método privado em `SolidusMeta::Event` com o nome em snake_case (`ViewContent` → `view_content`). Ele recebe as opções passadas ao job, define `@order` e retorna `path` e, opcionalmente, `event_id` e `custom_data` (que sobrescreve os campos padrão). Sem `event_id`, o id é `<número do pedido>-<event_time>`, então cada disparo conta como um evento separado. Defina um `event_id` fixo quando o evento só pode contar uma vez por pedido, como o `Purchase`.

data/app/controllers/concerns/solidus_meta/controller_helpers.rb

@@ -2,14 +2,64 @@ module SolidusMeta
   module ControllerHelpers
     extend ActiveSupport::Concern
 
+    BROWSER_EVENTS_KEY = :solidus_meta_browser_events
+    TRACKED_PURCHASES_KEY = :solidus_meta_tracked_purchases
+
+    included do
+      before_action :store_meta_click_id
+      helper SolidusMeta::PixelHelper
+    end
+
     private
 
+    def track_meta_event(event_name, **options)
+      return if request.headers["X-Sec-Purpose"] == "prefetch"
+
+      browser_event = SolidusMeta::Event.new.browser_data(event_name, **options)
+      event_id = browser_event[:event_id] || SecureRandom.uuid
+
+      SolidusMeta::EventJob.perform_later(event_name, event_id:, **options, **meta_tracking_data)
+      queue_meta_browser_event(event_name, event_id, browser_event[:custom_data])
+      mark_meta_purchase_tracked(event_id) if event_name == "Purchase"
+    end
+
+    def track_meta_purchase_in_browser(order)
+      return unless order.complete? && order.completed_at > 1.day.ago
+      return if Array(session[TRACKED_PURCHASES_KEY]).include?(order.number)
+
+      browser_event = SolidusMeta::Event.new.browser_data("Purchase", order_id: order.id)
+      queue_meta_browser_event("Purchase", browser_event[:event_id], browser_event[:custom_data])
+      mark_meta_purchase_tracked(order.number)
+    end
+
+    def queue_meta_browser_event(event_name, event_id, custom_data)
+      session[BROWSER_EVENTS_KEY] = Array(session[BROWSER_EVENTS_KEY]).last(4) + [{"name" => event_name, "event_id" => event_id, "custom_data" => custom_data.as_json}]
+    end
+
+    # O cookie de sessão tem limite de 4KB, então só guarda os pedidos mais recentes.
+    def mark_meta_purchase_tracked(order_number)
+      session[TRACKED_PURCHASES_KEY] = Array(session[TRACKED_PURCHASES_KEY]).last(9) + [order_number]
+    end
+
+    # O pixel grava o _fbc via JavaScript e o Safari apaga esses cookies em 7 dias; gravado pelo servidor ele dura os 90 dias da janela de atribuição.
+    def store_meta_click_id
+      fbclid = params[:fbclid].presence
+      return if fbclid.nil? || cookies[:_fbc].to_s.end_with?(".#{fbclid}")
+
+      cookies[:_fbc] = {value: "fb.1.#{(Time.current.to_f * 1000).to_i}.#{fbclid}", expires: 90.days, domain: :all}
+    end
+
     def cookies_meta
       {fbp: cookies[:_fbp], fbc: cookies[:_fbc]}
     end
 
     def meta_tracking_data
-      {cookies_meta:, ahoy_visit_id: (current_visit&.id if respond_to?(:current_visit, true))}
+      {
+        cookies_meta:,
+        ahoy_visit_id: (current_visit&.id if respond_to?(:current_visit, true)),
+        client_ip_address: request.remote_ip,
+        client_user_agent: request.user_agent
+      }
     end
   end
 end

data/app/helpers/solidus_meta/pixel_helper.rb

@@ -0,0 +1,20 @@
+module SolidusMeta
+  module PixelHelper
+    def meta_pixel_user_data(order: nil, user: nil, external_id: nil)
+      SolidusMeta::UserData.new(order:, user:, external_id:).to_h
+    end
+
+    def meta_pixel_events_tag
+      # O Turbo pré-carrega links no hover; sem isso a fila seria consumida por uma página que talvez nunca apareça.
+      return if request.headers["X-Sec-Purpose"] == "prefetch"
+
+      events = session.delete(SolidusMeta::ControllerHelpers::BROWSER_EVENTS_KEY)
+      return if events.blank?
+
+      calls = events.map do |event|
+        "fbq('track', #{event["name"].to_json}, #{event["custom_data"].to_json}, {eventID: #{event["event_id"].to_json}});"
+      end
+      javascript_tag("if (window.fbq) { #{calls.join(" ")} }", nonce: true)
+    end
+  end
+end

data/app/jobs/solidus_meta/base_job.rb

@@ -1,5 +1,5 @@
 module SolidusMeta
   class BaseJob < ActiveJob::Base
-    retry_on Ac::TooManyRequestsError, wait: :polynomially_longer, attempts: 5
+    retry_on Ac::TooManyRequestsError, Ac::ServerError, SolidusMeta::ConnectionError, wait: :polynomially_longer, attempts: 8
   end
 end

data/app/models/solidus_meta/client.rb

@@ -24,6 +24,10 @@ module SolidusMeta
         ]
       }
       post("#{@pixel_id}/events", body:, params:)
+    rescue Ac::AcError => e
+      # Timeout e falha de conexão chegam como AcError genérico com código 0, misturados com erros 4xx que não adianta reenviar.
+      raise ConnectionError, e.message if e.response.response.code.zero?
+      raise
     end
   end
 end

data/app/models/solidus_meta/event.rb

@@ -1,6 +1,6 @@
 module SolidusMeta
   class Event
-    EVENTS = %w[AddToCart InitiateCheckout AddPaymentInfo Purchase].freeze
+    EVENTS = %w[ViewContent AddToCart InitiateCheckout AddPaymentInfo Purchase CompleteRegistration Search].freeze
 
     attr_reader :order
 
@@ -8,26 +8,44 @@ module SolidusMeta
       @client = client
     end
 
-    def track(event_name, cookies_meta:, ahoy_visit_id: nil, event_time: Time.current, **options)
+    def build(event_name, **options)
       raise Error, "evento não suportado: #{event_name}" unless EVENTS.include?(event_name)
       event = send(event_name.underscore, **options)
-      event_id = event[:event_id] || "#{order.number}-#{event_time.to_time.to_i}"
 
-      @client.send_event(
-        event_name,
-        event_time:,
-        event_id:,
-        event_source_url: File.join(SolidusMeta.config.store_url(order.store), event[:path]),
-        user_data: user_data(cookies_meta, ahoy_visit_id, fallback: event[:fallback]),
+      {
+        event_id: event[:event_id],
+        event_source_url: File.join(SolidusMeta.config.store_url(order&.store), event[:path]),
+        user: event[:user],
         custom_data: {
-          currency: order.currency,
-          value: order.total.to_f,
-          order_id: order.number,
-          content_type: "product",
-          contents: content_line_items,
-          **address_data,
+          **(event.fetch(:order_data, true) ? order_custom_data : {}),
           **event.fetch(:custom_data, {})
         }.compact
+      }
+    end
+
+    def browser_data(event_name, **options)
+      event = build(event_name, **options)
+      {event_id: event[:event_id], custom_data: event[:custom_data].except(:contents)}
+    end
+
+    def track(event_name, cookies_meta:, event_id: nil, ahoy_visit_id: nil, client_ip_address: nil, client_user_agent: nil, event_time: Time.current, **options)
+      event = build(event_name, **options)
+      visit = Ahoy::Visit.find_by(id: ahoy_visit_id) if ahoy_visit_id && defined?(Ahoy::Visit)
+      cookies_meta = cookies_meta.to_h.with_indifferent_access
+
+      @client.send_event(
+        event_name,
+        event_time:,
+        event_id: event_id || event[:event_id] || "#{order.number}-#{event_time.to_time.to_i}",
+        event_source_url: event[:event_source_url],
+        user_data: {
+          **UserData.new(order:, user: event[:user]).hashed,
+          client_ip_address: visit&.ip || client_ip_address,
+          client_user_agent: visit&.user_agent || client_user_agent,
+          fbp: cookies_meta[:fbp],
+          fbc: cookies_meta[:fbc]
+        }.compact,
+        custom_data: event[:custom_data]
       )
     end
 
@@ -40,10 +58,10 @@ module SolidusMeta
       {
         event_id: "#{line_item.id}-#{line_item.updated_at.to_i}",
         path: "carrinho",
-        fallback: "sem usuário",
         custom_data: {
           currency: line_item.currency,
-          value: line_item.total.to_f,
+          value: (line_item.price * quantity.to_i).to_f,
+          content_ids: [line_item.sku],
           contents: [content_line_item(line_item, quantity)]
         }
       }
@@ -55,7 +73,7 @@ module SolidusMeta
       {
         path: "checkout/address/edit",
         custom_data: {
-          num_items: order.line_items.count
+          num_items: order.line_items.sum(&:quantity)
         }
       }
     end
@@ -67,9 +85,6 @@ module SolidusMeta
       {
         path: "checkout/payment",
         custom_data: {
-          currency: payment.currency,
-          value: payment.amount.to_f,
-          content_id: payment.number,
           payment_type: payment.payment_method.name
         }
       }
@@ -80,77 +95,86 @@ module SolidusMeta
 
       {
         event_id: order.number,
-        path: "pedidos"
+        path: "pedidos/#{order.number}",
+        custom_data: {
+          num_items: order.line_items.sum(&:quantity)
+        }
       }
     end
 
-    def user_data(cookies_meta, ahoy_visit_id, fallback: nil)
-      cookies_meta = cookies_meta.to_h.with_indifferent_access
-      visit = Ahoy::Visit.find_by(id: ahoy_visit_id) if ahoy_visit_id && defined?(Ahoy::Visit)
-
-      {
-        em: sha256(email || fallback),
-        fn: sha256(name || fallback),
-        ph: sha256(phone),
-        ct: sha256(address&.city&.downcase),
-        st: sha256(address&.state&.name&.downcase),
-        zp: sha256(address&.zipcode),
-        country: sha256(country),
-        external_id: address&.id&.to_s,
-        client_user_agent: visit&.user_agent,
-        client_ip_address: visit&.ip,
-        fbp: cookies_meta[:fbp],
-        fbc: cookies_meta[:fbc]
-      }.compact
-    end
+    def complete_registration(user:, order_id: nil)
+      @order = Spree::Order.find_by(id: order_id) if order_id
 
-    def address_data
       {
-        postal_code: address&.zipcode,
-        region: state,
-        country:
+        event_id: "registration-#{user.id}",
+        path: "cadastro",
+        user:,
+        order_data: false,
+        custom_data: {
+          status: true
+        }
       }
     end
 
-    def content_line_items
-      order.line_items.map { |line_item| content_line_item(line_item, line_item.quantity) }
-    end
+    def view_content(variant_ids:, order_id: nil)
+      @order = Spree::Order.find_by(id: order_id) if order_id
+      variants = Spree::Variant.where(id: variant_ids).includes(:product).index_by(&:id).values_at(*variant_ids).compact
+      main_variant = variants.first
 
-    def content_line_item(line_item, quantity)
       {
-        id: line_item.sku,
-        quantity:,
-        item_price: line_item.price.to_f
+        path: "produtos/#{main_variant.product.slug}",
+        order_data: false,
+        custom_data: {
+          currency: main_variant.default_price&.currency || Spree::Config.currency,
+          value: main_variant.price.to_f,
+          content_type: "product",
+          content_ids: variants.map(&:sku),
+          contents: variants.map { |variant| {id: variant.sku, quantity: 1, item_price: variant.price.to_f} }
+        }
       }
     end
 
-    def address
-      order.ship_address || order.user&.address
-    end
+    def search(search_string:, content_ids: [], order_id: nil)
+      @order = Spree::Order.find_by(id: order_id) if order_id
 
-    def state
-      address&.state&.name&.downcase
+      {
+        path: "busca?#{{keywords: search_string}.to_query}",
+        order_data: false,
+        custom_data: {
+          search_string:,
+          content_type: "product",
+          content_ids:
+        }
+      }
     end
 
-    def country
-      address&.country&.name&.downcase
-    end
+    def order_custom_data
+      return {} unless order
 
-    def name
-      (order.name || order.user&.name)&.downcase
+      {
+        currency: order.currency,
+        value: products_value,
+        order_id: order.number,
+        content_type: "product",
+        content_ids: order.line_items.map(&:sku),
+        contents: content_line_items
+      }
     end
 
-    def email
-      (order.email || order.user&.email)&.downcase
+    def products_value
+      (order.total - order.shipment_total - order.shipments.sum(&:promo_total)).to_f
     end
 
-    def phone
-      return unless address&.phone.present?
-      "55" + address.phone.remove(/\D/).remove(/^55/)
+    def content_line_items
+      order.line_items.map { |line_item| content_line_item(line_item, line_item.quantity) }
     end
 
-    def sha256(value)
-      Digest::SHA256.hexdigest(value.strip) if value.present?
+    def content_line_item(line_item, quantity)
+      {
+        id: line_item.sku,
+        quantity: quantity.to_i,
+        item_price: line_item.price.to_f
+      }
     end
   end
 end

data/app/models/solidus_meta/user_data.rb

@@ -0,0 +1,79 @@
+module SolidusMeta
+  class UserData
+    def initialize(order: nil, user: nil, external_id: nil)
+      @order = order
+      @user = user || order&.user
+      @external_id = external_id
+    end
+
+    def to_h
+      {
+        em: email,
+        ph: phone,
+        fn: first_name,
+        ln: last_name,
+        ct: city,
+        st: state,
+        zp: zipcode,
+        country:,
+        external_id:
+      }.compact_blank
+    end
+
+    def hashed
+      to_h.transform_values { |value| value.match?(/\A\h{64}\z/) ? value : Digest::SHA256.hexdigest(value) }
+    end
+
+    private
+
+    attr_reader :order, :user
+
+    def address
+      order&.ship_address || order&.bill_address || user.try(:ship_address) || user.try(:bill_address)
+    end
+
+    def email
+      (order&.email.presence || user.try(:email).presence || user.try(:email_address))&.strip&.downcase
+    end
+
+    def phone
+      digits = address&.phone.to_s.gsub(/\D/, "").sub(/\A0+/, "")
+      return if digits.blank?
+
+      digits = "55#{digits}" if digits.length.in?(10..11)
+      digits if digits.length.in?(12..13)
+    end
+
+    def name_parts
+      @name_parts ||= (order&.name.presence || address&.name.presence || user.try(:name)).to_s.downcase.split
+    end
+
+    def first_name
+      name_parts.first
+    end
+
+    def last_name
+      name_parts.last if name_parts.size > 1
+    end
+
+    def city
+      I18n.transliterate(address.city.to_s).downcase.gsub(/[^a-z]/, "") if address
+    end
+
+    def state
+      (address.state&.abbr || address.state_name).to_s.downcase if address
+    end
+
+    def zipcode
+      address&.zipcode.to_s.gsub(/\D/, "")
+    end
+
+    def country
+      (address&.country || Spree::Country.default)&.iso&.downcase
+    end
+
+    def external_id
+      @external_id.presence || (SolidusMeta.config.external_id(order) if order)
+    end
+  end
+end

data/lib/solidus_meta/configuration.rb

@@ -2,7 +2,7 @@
 
 module SolidusMeta
   class Configuration
-    attr_writer :pixel_id, :access_token, :store_url
+    attr_writer :pixel_id, :access_token, :store_url, :external_id
 
     def pixel_id
       @pixel_id || ENV["META_PIXEL_ID"]
@@ -18,5 +18,9 @@ module SolidusMeta
       raise Error, "store_url não configurado: defina SolidusMeta.config.store_url, META_STORE_URL ou a url da loja" unless url
       url.start_with?("http") ? url : "https://#{url}"
     end
+
+    def external_id(order)
+      (@external_id || ->(o) { o.user_id&.to_s || o.guest_token }).call(order)&.to_s
+    end
   end
 end

data/lib/solidus_meta/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidusMeta
-  VERSION = "1.1.1"
+  VERSION = "2.0.0"
 end

data/lib/solidus_meta.rb

@@ -7,6 +7,7 @@ require "solidus_meta/engine"
 
 module SolidusMeta
   class Error < StandardError; end
+  class ConnectionError < Error; end
 
   def self.config
     @config ||= Configuration.new

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solidus_meta
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 2.0.0
 platform: ruby
 authors:
 - marialuiza1324
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-29 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ac
@@ -61,10 +61,12 @@ extra_rdoc_files: []
 files:
 - README.md
 - app/controllers/concerns/solidus_meta/controller_helpers.rb
+- app/helpers/solidus_meta/pixel_helper.rb
 - app/jobs/solidus_meta/base_job.rb
 - app/jobs/solidus_meta/event_job.rb
 - app/models/solidus_meta/client.rb
 - app/models/solidus_meta/event.rb
+- app/models/solidus_meta/user_data.rb
 - lib/solidus_meta.rb
 - lib/solidus_meta/configuration.rb
 - lib/solidus_meta/engine.rb