solidus_meta 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9df7c2815f8fcf61690d5f9728822ed9d2e38c2395bfd3a903e7765b8e629fc
+  data.tar.gz: 79881489f2cd955db11445883dd359fa415392525b33728d734f5ebcb94be54c
+SHA512:
+  metadata.gz: 27f7e2c7c2c6301b40f1053d8dec9a531acb5cf34081b2ae5bceddccb8e8a9f022fca3dddfd6ca543690cda4542723652bf586fa389e93015e3a38326723a6dc
+  data.tar.gz: 9dfbf78a4f965421222ee53d00051727a5600c6e3f3b216a7329ad5063d199da37bd21094bffd130f916c493572cc7df7f13e19bd8611f38afeaf149c0538e2d

data/README.md

@@ -0,0 +1,57 @@
+# 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`.
+
+## Instalação
+
+```ruby
+gem "solidus_meta"
+```
+
+## Configuração
+
+Por padrão lê `META_PIXEL_ID`, `META_ACCESS_TOKEN` e `META_STORE_URL` do ambiente. Para sobrescrever:
+
+```ruby
+# config/initializers/solidus_meta.rb
+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"
+end
+```
+
+`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.
+
+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`.
+
+## Uso
+
+Inclua o helper no controller:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include SolidusMeta::ControllerHelpers
+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:
+
+```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)
+```
+
+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 `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 `event_id`, `path` e, opcionalmente, `fallback` e `custom_data` (que sobrescreve os campos padrão).

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

@@ -0,0 +1,15 @@
+module SolidusMeta
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    private
+
+    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))}
+    end
+  end
+end

data/app/jobs/solidus_meta/base_job.rb

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

data/app/jobs/solidus_meta/event_job.rb

@@ -0,0 +1,7 @@
+module SolidusMeta
+  class EventJob < BaseJob
+    def perform(event_name, cookies_meta:, ahoy_visit_id: nil, **options)
+      Event.new.track(event_name, cookies_meta:, ahoy_visit_id:, event_time: enqueued_at || Time.current, **options)
+    end
+  end
+end

data/app/models/solidus_meta/client.rb

@@ -0,0 +1,29 @@
+module SolidusMeta
+  class Client < Ac::Base
+    BASE_URL = "https://graph.facebook.com/v24.0/"
+    SAVE_RESPONSES = true
+
+    def initialize(pixel_id: SolidusMeta.config.pixel_id, access_token: SolidusMeta.config.access_token)
+      @pixel_id = pixel_id
+      @meta_access_token = access_token
+    end
+
+    def send_event(event_name, event_id:, event_source_url:, event_time: Time.current, user_data: {}, custom_data: {})
+      params = {access_token: @meta_access_token}
+      body = {
+        data: [
+          {
+            event_name:,
+            event_time: event_time.to_time.to_i,
+            action_source: "website",
+            event_source_url:,
+            event_id:,
+            user_data:,
+            custom_data:
+          }
+        ]
+      }
+      post("#{@pixel_id}/events", body:, params:)
+    end
+  end
+end

data/app/models/solidus_meta/event.rb

@@ -0,0 +1,147 @@
+module SolidusMeta
+  class Event
+    EVENTS = %w[AddToCart InitiateCheckout AddPaymentInfo Purchase].freeze
+
+    attr_reader :order
+
+    def initialize(client: Client.new)
+      @client = client
+    end
+
+    def track(event_name, cookies_meta:, ahoy_visit_id: nil, event_time: Time.current, **options)
+      raise Error, "evento não suportado: #{event_name}" unless EVENTS.include?(event_name)
+      event = send(event_name.underscore, **options)
+
+      @client.send_event(
+        event_name,
+        event_time:,
+        event_id: event[: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]),
+        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(:custom_data, {})
+        }.compact
+      )
+    end
+
+    private
+
+    def add_to_cart(line_item_id:, quantity:)
+      line_item = Spree::LineItem.find(line_item_id)
+      @order = line_item.order
+
+      {
+        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,
+          contents: [content_line_item(line_item, quantity)]
+        }
+      }
+    end
+
+    def initiate_checkout(order_id:)
+      @order = Spree::Order.find(order_id)
+
+      {
+        event_id: order.number,
+        path: "checkout/address/edit",
+        custom_data: {num_items: order.line_items.count}
+      }
+    end
+
+    def add_payment_info(payment_id:)
+      payment = Spree::Payment.find(payment_id)
+      @order = payment.order
+
+      {
+        event_id: order.number,
+        path: "checkout/payment",
+        custom_data: {
+          currency: payment.currency,
+          value: payment.amount.to_f,
+          content_id: payment.number
+        }
+      }
+    end
+
+    def purchase(order_id:)
+      @order = Spree::Order.find(order_id)
+
+      {event_id: order.number, path: "pedidos"}
+    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 address_data
+      {
+        postal_code: address&.zipcode,
+        region: state,
+        country:
+      }
+    end
+
+    def content_line_items
+      order.line_items.map { |line_item| content_line_item(line_item, line_item.quantity) }
+    end
+
+    def content_line_item(line_item, quantity)
+      {id: line_item.sku, quantity:, item_price: line_item.price.to_f}
+    end
+
+    def address
+      order.ship_address || order.user&.address
+    end
+
+    def state
+      address&.state&.name&.downcase
+    end
+
+    def country
+      address&.country&.name&.downcase
+    end
+
+    def name
+      (order.name || order.user&.name)&.downcase
+    end
+
+    def email
+      (order.email || order.user&.email)&.downcase
+    end
+
+    def phone
+      return unless address&.phone.present?
+      "55" + address.phone.remove(/\D/).remove(/^55/)
+    end
+
+    def sha256(value)
+      Digest::SHA256.hexdigest(value.strip) if value.present?
+    end
+  end
+end

data/lib/solidus_meta/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SolidusMeta
+  class Configuration
+    attr_writer :pixel_id, :access_token, :store_url
+
+    def pixel_id
+      @pixel_id || ENV["META_PIXEL_ID"]
+    end
+
+    def access_token
+      @access_token || ENV["META_ACCESS_TOKEN"]
+    end
+
+    def store_url(store = nil)
+      url = @store_url.presence || ENV["META_STORE_URL"].presence || store&.url.presence
+
+      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
+  end
+end

data/lib/solidus_meta/engine.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "solidus_core"
+require "solidus_support"
+
+module SolidusMeta
+  class Engine < Rails::Engine
+    include SolidusSupport::EngineExtensions
+
+    isolate_namespace SolidusMeta
+
+    engine_name "solidus_meta"
+  end
+end

data/lib/solidus_meta/version.rb

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

data/lib/solidus_meta.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "ac"
+require "solidus_meta/version"
+require "solidus_meta/configuration"
+require "solidus_meta/engine"
+
+module SolidusMeta
+  class Error < StandardError; end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.configure
+    yield config
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: solidus_meta
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- marialuiza1324
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ac
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: solidus_core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: solidus_support
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Envia eventos para a Conversions API da Meta a partir de pedidos do Solidus.
+email:
+- marialuiza.nerypinto@yahoo.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- app/controllers/concerns/solidus_meta/controller_helpers.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
+- lib/solidus_meta.rb
+- lib/solidus_meta/configuration.rb
+- lib/solidus_meta/engine.rb
+- lib/solidus_meta/version.rb
+homepage: https://github.com/todasessascoisas/solidus_meta
+licenses: []
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Eventos da Conversions API da Meta para lojas Solidus
+test_files: []