solidus_klaviyo

This extension allows you to integrate your Solidus store with Klaviyo.

Installation

Add solidus_klaviyo to your Gemfile:

gem 'solidus_klaviyo'

Bundle your dependencies and run the installation generator:

$ bundle
$ bundle exec rails g solidus_klaviyo:install

The generator will create an initializer at config/initializers/solidus_klaviyo.rb with the default configuration. Take a look at the file and customize it to fit your environment.

Usage

Subscribing users to lists

If you want to subscribe a user to a Klaviyo list, the extension provides a handy Ruby API to do that:

subscriber = SolidusKlaviyo::Subscriber.new('YOUR_LIST_ID')
subscriber.subscribe('[email protected]') # => true or raises SolidusKlaviyo::Subscriber::SubscriptionError 

We recommend using the built-in background job to subscribe users, in order to avoid blocking your web workers and slowing down the customer:

SolidusKlaviyo::SubscribeJob.perform_later('YOUR_LIST_ID', '[email protected]')

Subscribing all users upon signup

If you want to subscribe all users when they sign up, you can just set the default_list configuration option:

# config/initializers/solidus_klaviyo.rb
SolidusKlaviyo.configure do |config|
  # ...
  config.default_list = 'klaviyoListId'
end

Now, all users will be subscribed to the configured list automatically when their account is created.

Tracking events

The extension will send the following events to Klaviyo:

• Started Checkout: when an order transitions from the cart state to address.
• Placed Order: when an order is finalized.
• Ordered Product: for each item in a finalized order.
• Cancelled Order: when an order is cancelled.
• Created Account: when a user is created.
• Reset Password: when a user requests a password reset.

For the full payload of these events, look at the source code of the serializers and events.

Implementing custom events

If you have custom events you want to track with this gem, you can easily do so by creating a new event class and implementing the required methods:

module MyApp
  module KlaviyoEvents
    class SubscribedToNewsletter < SolidusKlaviyo::Event::Base
      def name
        'SubscribedToNewsletter'
      end

      def email
        user.email
      end

      def customer_properties
        SolidusKlaviyo::Serializer::Customer.serialize(user)
      end

      def properties
        {
          '$event_id' => user.id.to_s,
          '...' => '...',
        }
      end

      def time
        Time.zone.now
      end

      private

      def user
        payload.fetch(:user)
      end
    end 
  end 
end

Once you have created the class, the next step is to register your custom event when initializing the extension:

# config/initializers/solidus_klaviyo.rb
SolidusKlaviyo.configure do |config|
  config.events['subscribed_to_newsletter'] = MyApp::KlaviyoEvents::SubscribedToNewsletter
end

Your custom event is now properly configured! You can track it by enqueuing the TrackEventJob:

SolidusKlaviyo::TrackEventJob.perform_later('signed_up', user: user)

NOTE: You can follow the same exact pattern to override the built-in events.

Delivering emails through Klaviyo

If you plan to deliver your transactional emails through Klaviyo flows, you may want to disable the built-in emails that are delivered by Solidus and solidus_auth_devise.

In order to do that, you can set the disable_builtin_emails option in the extension's initializer:

# config/initializers/solidus_klaviyo.rb
SolidusKlaviyo.configure do |config|
  config.disable_builtin_emails = true
end

This will disable the following emails:

• Order confirmation
• Order cancellation
• Password reset

You'll have to re-implement the emails with Klaviyo.

Development

Testing the extension

First bundle your dependencies, then run bin/rake. bin/rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using bin/rake extension:test_app.

$ bundle
$ bin/rake

To run Rubocop static code analysis run

$ bundle exec rubocop

When testing your application's integration with this extension you may use its factories. Simply add this require statement to your spec_helper:

require 'solidus_klaviyo/factories'

Running the sandbox

To run this extension in a sandboxed Solidus application, you can run bin/sandbox. The path for the sandbox app is ./sandbox and bin/rails will forward any Rails commands to sandbox/bin/rails.

Here's an example:

$ bin/rails server
=> Booting Puma
=> Rails 6.0.2.1 application starting in development
* Listening on tcp://127.0.0.1:3000
Use Ctrl-C to stop

Releasing new versions

Your new extension version can be released using gem-release like this:

$ bundle exec gem bump -v VERSION --tag --push --remote upstream && gem release

License

Copyright (c) 2020 Nebulab Srls, released under the New BSD License.