{"id":23765784,"url":"https://github.com/solidusio-contrib/solidus_tracking","last_synced_at":"2026-03-07T09:31:37.537Z","repository":{"id":39753110,"uuid":"296382545","full_name":"solidusio-contrib/solidus_tracking","owner":"solidusio-contrib","description":"Data tracking extension for your Solidus store.","archived":false,"fork":false,"pushed_at":"2025-11-05T19:21:45.000Z","size":70,"stargazers_count":5,"open_issues_count":17,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-05T21:24:30.949Z","etag":null,"topics":["data","ecommerce","extension","segment","solidus","tracking"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solidusio-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-17T16:29:02.000Z","updated_at":"2025-11-05T19:20:52.000Z","dependencies_parsed_at":"2022-08-09T15:25:26.976Z","dependency_job_id":null,"html_url":"https://github.com/solidusio-contrib/solidus_tracking","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/solidusio-contrib/solidus_tracking","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_tracking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_tracking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_tracking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_tracking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solidusio-contrib","download_url":"https://codeload.github.com/solidusio-contrib/solidus_tracking/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_tracking/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30210833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T09:02:10.694Z","status":"ssl_error","status_checked_at":"2026-03-07T09:02:08.429Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data","ecommerce","extension","segment","solidus","tracking"],"created_at":"2024-12-31T23:17:38.904Z","updated_at":"2026-03-07T09:31:37.517Z","avatar_url":"https://github.com/solidusio-contrib.png","language":"Ruby","readme":"# solidus_tracking\n\n[![CircleCI](https://circleci.com/gh/solidusio-contrib/solidus_tracking.svg?style=svg)](https://circleci.com/gh/solidusio-contrib/solidus_tracking)\n\nThis extension provides a data tracking platform (think [Segment](https://segment.com), but\non-premise) for your Solidus store.\n\nIt has out-of-the-box support for the most common eCommerce events, as well as for delivering\ntransactional emails through an external service.\n\n| Service | Extension |\n| ------- | --------- |\n| [Klaviyo](https://klaviyo.com) | [solidus_klaviyo](https://github.com/solidusio-contrib/solidus_klaviyo) |\n\n## Installation\n\nAdd solidus_tracking to your Gemfile:\n\n```ruby\ngem 'solidus_tracking'\n```\n\nBundle your dependencies and run the installation generator:\n\n```console\n$ bundle\n$ bundle exec rails g solidus_tracking:install\n```\n\nThe generator will create an initializer at `config/initializers/solidus_tracking.rb` with the\ndefault configuration. Take a look at the file and customize it to fit your environment.\n\n## Usage\n\n### Tracking events\n\nThe extension will track the following events:\n\n- `Started Checkout`: when an order transitions from the `cart` state to `address`.\n- `Placed Order`: when an order is finalized.\n- `Ordered Product`: for each item in a finalized order.\n- `Fulfilled Order`: when all of an order's shipments are shipped.\n- `Cancelled Order`: when an order is cancelled.\n- `Created Account`: when a user is created.\n- `Reset Password`: when a user requests a password reset.\n\nFor the full payload of these events, look at the source code of the serializers and events.\n\n#### Implementing custom events\n\nIf you have custom events you want to track with this gem, you can easily do so by creating a new\nevent class and implementing the required methods:\n\n```ruby\nmodule MyApp\n  module Events\n    class SubscribedToNewsletter \u003c SolidusTracking::Event::Base\n      self.payload_serializer = 'MyApp::Serializers::User'\n\n      def name\n        'SubscribedToNewsletter'\n      end\n\n      def email\n        user.email\n      end\n\n      def customer_properties\n        self.class.customer_properties_serializer.serialize(user)\n      end\n\n      def properties\n        self.class.payload_serializer.serialize(user)\n      end\n\n      def time\n        Time.zone.now\n      end\n\n      private\n\n      def user\n        payload.fetch(:user)\n      end\n    end \n  end \nend\n```\n\nAs you can see, you will also have to create a serializer for your users:\n\n```ruby\nmodule MyApp\n  module Serializers\n    class UserSerializer \u003c SolidusTracking::Serializer::Base\n      def user\n        object\n      end\n\n      def as_json(_options = {})\n        {\n          'FirstName' =\u003e user.first_name,\n          'LastName' =\u003e user.last_name,\n          # ...\n        }\n      end\n    end\n  end\nend\n```\n\nOnce you have created the event and serializer, the next step is to register your custom event when\ninitializing the extension:\n\n```ruby\n# config/initializers/solidus_tracking.rb\nSolidusTracking.configure do |config|\n  config.events['subscribed_to_newsletter'] = MyApp::Events::SubscribedToNewsletter\nend\n```\n\nYour custom event is now properly configured! You can track it by calling `.track_later`:\n\n```ruby\nSolidusTracking.track_later('subscribed_to_newsletter', user: user)\n```\n\n*NOTE:* You can follow the same exact pattern to override the built-in events.\n\n### Changing the serializers for built-in events\n\nIf you need to change the customer properties serializer or the payload serializer for one or more\nevents, there's no need to monkey-patch or override them. You can simply set \n`customer_properties_serializer` and/or `payload_serializer` in an initializer:\n\n```ruby\n# config/initializers/solidus_tracking.rb\n\nSolidusTracking::Event::CancelledOrder.customer_properties_serializer = 'MyApp::Serializers::CustomerProperties'\nSolidusTracking::Event::CancelledOrder.payload_serializer = 'MyApp::Serializers::Order'\n```\n\nIf need to change the customer properties serializer for _all_ your events (which will usually be\nthe case), you can loop through the `.events` setting:\n\n```ruby\n# config/initializers/solidus_tracking.rb\n\nSolidusTracking.configuration.events.each_value do |event_klass|\n  event_klass.constantize.customer_properties_serializer = 'MyApp::Serializers::CustomerProperties'\nend\n```\n\nMake sure to do this _after_ defining any custom events!\n\n### Delivering emails through a tracker\n\nIf you plan to deliver your transactional emails through a tracker (e.g., Klaviyo), you may want to\ndisable the built-in emails that are delivered by Solidus and solidus_auth_devise.\n\nIn order to do that, you can set the `disable_builtin_emails` option in the extension's initializer:\n\n```ruby\n# config/initializers/solidus_tracking.rb\nSolidusTracking.configure do |config|\n  config.disable_builtin_emails = true\nend\n```\n\nThis will disable the following emails:\n\n- Order confirmation\n- Order cancellation\n- Password reset\n- Carton shipped\n\nYou'll have to re-implement the emails with a tracker.\n\n### Disabling automatic event tracking\n\nIf you want to disable the out-of-the-box event tracking, you can do so on a per-event basis by\nacting on the `automatic_events` configuration option:\n\n```ruby\n# config/initializers/solidus_tracking.rb\nSolidusTracking.configure do |config|\n  config.automatic_events.delete('placed_order')\nend\n```\n\nYou may also disable the built-in event tracking completely, if you only want to track events\nmanually:\n\n```ruby\n# config/initializers/solidus_tracking.rb\nSolidusTracking.configure do |config|\n  config.automatic_events.clear\nend\n```\n\n### Test mode\n\nYou can enable test mode to mock all API calls instead of performing them:\n\n```ruby\n# config/initializers/solidus_tracking.rb\nSolidusTracking.configure do |config|\n  config.test_mode = true\nend\n```\n\nThis spares you the need to use VCR and similar.\n \nWhen in test mode, you can also use our custom RSpec matchers to check if an event has been tracked:\n\n```ruby\nrequire 'solidus_tracking/testing_support/matchers'\n\nRSpec.describe 'My tracking integration' do\n  it 'tracks events' do\n    SolidusTracking.track_now 'custom_event', foo: 'bar'\n\n    expect(SolidusTracking).to have_tracked_event(CustomEvent)\n      .with(foo: 'bar')\n  end\nend\n```\n\n## Development\n\n### Testing the extension\n\nFirst bundle your dependencies, then run `bin/rake`. `bin/rake` will default to building the dummy\napp if it does not exist, then it will run specs. The dummy app can be regenerated by using\n`bin/rake extension:test_app`.\n\n```console\n$ bundle\n$ bin/rake\n```\n\nTo run [Rubocop](https://github.com/bbatsov/rubocop) static code analysis run\n\n```console\n$ bundle exec rubocop\n```\n\nWhen testing your application's integration with this extension you may use its factories.\nSimply add this require statement to your spec_helper:\n\n```ruby\nrequire 'solidus_tracking/factories'\n```\n\n### Running the sandbox\n\nTo run this extension in a sandboxed Solidus application, you can run `bin/sandbox`. The path for\nthe sandbox app is `./sandbox` and `bin/rails` will forward any Rails commands to\n`sandbox/bin/rails`.\n\nHere's an example:\n\n```console\n$ bin/rails server\n=\u003e Booting Puma\n=\u003e Rails 6.0.2.1 application starting in development\n* Listening on tcp://127.0.0.1:3000\nUse Ctrl-C to stop\n```\n\n### Releasing new versions\n\nYour new extension version can be released using `gem-release` like this:\n\n```console\n$ bundle exec gem bump -v VERSION --tag --push --remote upstream \u0026\u0026 gem release\n```\n\n## License\n\nCopyright (c) 2020 Nebulab Srls, released under the New BSD License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio-contrib%2Fsolidus_tracking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolidusio-contrib%2Fsolidus_tracking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio-contrib%2Fsolidus_tracking/lists"}