customerio 5.6.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e400cd48d515843a8d229b0d395c118f57b989d780220e187695c20cc6b13109
-  data.tar.gz: dd2c8d4a83fdfb02f6cda4084ed5f54d641b157ecffb6ff93357526fcad6eb73
+  metadata.gz: 9563849000bf5d39f2e0f02aebe93072d42f6eb02343d7d444f964fc86ee3a3f
+  data.tar.gz: 3f4e966503aa9526546a1767580f141da91f06c3ab539c5ee796bedce550d15d
 SHA512:
-  metadata.gz: 8515504c0a52b34fd5aca03393947270f8374c53bc6e7285ef2d49dbd9625602ca16b396189f879bc68ca4b1f8fee0dae5b0d91724638a9bee412cb12cda5092
-  data.tar.gz: 3b985d7390279186c3eb110ba7a43771ac10b8f764794db640b5daf49e7b876bdcd539772370c757a5f71db7285e6053bd29cf1b9afc5802b29e7e056f8a7488
+  metadata.gz: 7230e937323c875bc45e6dbd5a3d499f68ca6df4bf7fc414b0e425f8c0ea1b85bab5315e56887f11f184ee013c33d2d5b0d7d6373069a5a8a17ae397a980a9ff
+  data.tar.gz: 6742e5db8afbd888ce0eef0e9667f96578307142564f70b2151663fa4e17dc00df1b09b4db667fb8294a235ed92d1059af08ad84498136fce91739415cba4524

data/CHANGELOG.markdown

@@ -1,3 +1,8 @@
+## Customerio 5.7.0 - Unreleased
+### Added
+- Added `track_delivery_metric` to `Client` for reporting delivery metrics via the `/api/v1/metrics` endpoint, replacing the deprecated `/push/events` endpoint. Supports metrics: opened, clicked, converted, delivered, bounced, deferred, dropped, and spammed.
+- Added `DELIVERY_*` constants and `VALID_DELIVERY_METRICS` to `Customerio::Client`.
+
 ## Customerio 5.4.0 - June 13, 2025
 ### Changed
 - Added `send_sms` to `APIClient` and `SendSMSRequest` to support sending transactional push notifications.

data/README.md

@@ -7,10 +7,12 @@
 [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blueviolet?logo=gitpod)](https://gitpod.io/#https://github.com/customerio/customerio-ruby/)
 [![ci](https://github.com/customerio/customerio-ruby/actions/workflows/main.yml/badge.svg)](https://github.com/customerio/customerio-ruby/actions/workflows/main.yml)
 
-# Customer.io Ruby 
+# Customer.io Ruby
 
 A ruby client for the [Customer.io Journeys Track API](https://customer.io/docs/api/track/).
 
+Supported Ruby versions are the actively maintained Ruby lines, starting at Ruby 3.3.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -30,7 +32,7 @@ Or install it yourself:
 ### Before we get started: API client vs. JavaScript snippet
 
 It's helpful to know that everything below can also be accomplished
-through the [Customer.io JavaScript snippet](https://customer.io/docs/javascript-quick-start/).
+through the [Customer.io JavaScript client](https://docs.customer.io/integrations/data-in/connections/javascript/js-source/).
 
 In many cases, using the JavaScript snippet will be easier to integrate with
 your app, but there are several reasons why using the API client is useful:
@@ -58,6 +60,28 @@ $customerio = Customerio::Client.new("YOUR SITE ID", "YOUR API SECRET KEY", regi
 
 `region` is optional and takes one of two values—`US` or `EU`. If you do not specify your region, we assume that your account is based in the US (`US`). If your account is based in the EU and you do not provide the correct region (`EU`), we'll route requests to our EU data centers accordingly, however this may cause data to be logged in the US. 
 
+#### Timeouts
+
+Both clients accept a `timeout` option (in seconds) that controls the HTTP connect and read timeouts. The default is 10 seconds.
+
+```ruby
+# Track API client with a 3-second timeout
+$customerio = Customerio::Client.new("YOUR SITE ID", "YOUR API SECRET KEY", timeout: 3)
+
+# Transactional API client with a 3-second timeout
+client = Customerio::APIClient.new("your API key", timeout: 3)
+```
+
+When a request exceeds the timeout, Ruby raises `Net::OpenTimeout` (connection phase) or `Net::ReadTimeout` (waiting for response). You can rescue both:
+
+```ruby
+begin
+  $customerio.identify(id: 5, email: "person@example.com")
+rescue Net::OpenTimeout, Net::ReadTimeout => e
+  # handle timeout
+end
+```
+
 ### Identify logged in customers
 
 Tracking data of logged in customers is a key part of [Customer.io](https://customer.io). In order to
@@ -187,14 +211,32 @@ encourage your customers to perform an action.
 #                          event. These attributes can be used in your triggers to control who should
 #                          receive the triggered email. You can set any number of data values.
 
-$customerio.track(5, "purchase", :type => "socks", :price => "13.99")
+$customerio.track(5, "purchase", { :type => "socks", :price => "13.99" })
 ```
 
-**Note:** If you want to track events which occurred in the past, you can include a `timestamp` attribute
+**Note:** If you want to track events which occurred in the past, you can pass a `timestamp` keyword argument
 (in seconds since the epoch), and we'll use that as the date the event occurred.
 
 ```ruby
-$customerio.track(5, "purchase", :type => "socks", :price => "13.99", :timestamp => 1365436200)
+$customerio.track(5, "purchase", { :type => "socks", :price => "13.99" }, timestamp: 1365436200)
+```
+
+#### Deduplicating events
+
+You can provide a [ULID](https://github.com/ulid/spec) `id` to deduplicate events. If two events have the same `id`, Customer.io won't process the event a second time.
+
+```ruby
+$customerio.track(5, "purchase", { :type => "socks" }, id: "01BX5ZZKBKACTAV9WEVGEMMVRY")
+
+$customerio.track_anonymous("anon-id", "purchase", { :type => "socks" }, id: "01BX5ZZKBKACTAV9WEVGEMMVRY")
+```
+
+You can also pass `timestamp` as a keyword argument (epoch seconds) instead of including it in the attributes hash:
+
+```ruby
+$customerio.track(5, "purchase", { :type => "socks" }, timestamp: 1561231234)
+
+$customerio.track(5, "purchase", { :type => "socks" }, id: "01BX5ZZKBKACTAV9WEVGEMMVRY", timestamp: 1561231234)
 ```
 
 ### Tracking anonymous events
@@ -209,7 +251,7 @@ Anonymous events cannot trigger campaigns by themselves. To trigger a campaign,
 # name (required)                   - the name of the event you want to track.
 # attributes (optional)             - related information you want to attach to the event.
 
-$customerio.track_anonymous(anonymous_id, "product_view", :type => "socks" )
+$customerio.track_anonymous(anonymous_id, "product_view", { :type => "socks" })
 ```
 
 Use the `recipient` attribute to specify the email address to send the messages to. [See our documentation on how to use anonymous events for more details](https://customer.io/docs/invite-emails/).
@@ -219,7 +261,7 @@ Use the `recipient` attribute to specify the email address to send the messages
 If you previously sent [invite events](https://customer.io/docs/anonymous-invite-emails/), you can achieve the same functionality by sending an anonymous event with `nil` for the anonymous identifier. To send anonymous invites, your event *must* include a `recipient` attribute. 
 
 ```ruby
-$customerio.track_anonymous(nil, "invite", :recipient => "new.person@example.com" )
+$customerio.track_anonymous(nil, "invite", { :recipient => "new.person@example.com" })
 ```
 
 ### Adding a mobile device
@@ -245,6 +287,26 @@ Deleting a device token will remove it from the associated customer to stop furt
 $customerio.delete_device(5, "my_device_token")
 ```
 
+### Tracking delivery metrics
+
+Report delivery metrics using the `track_delivery_metric` method, which calls the `/api/v1/metrics` endpoint. This replaces the deprecated `/push/events` endpoint. The `delivery_id` is required. Valid metrics are: `opened`, `clicked`, `converted`, `delivered`, `bounced`, `deferred`, `dropped`, `spammed`.
+
+```ruby
+$customerio.track_delivery_metric("opened", delivery_id: "RPILAgUBcRillFPDbQQ=")
+
+$customerio.track_delivery_metric("clicked", {
+  delivery_id: "RPILAgUBcRillFPDbQQ=",
+  timestamp: 1561231234,
+  href: "https://example.com/link",
+  recipient: "user@example.com"
+})
+
+$customerio.track_delivery_metric("bounced", {
+  delivery_id: "RPILAgUBcRillFPDbQQ=",
+  reason: "mailbox full"
+})
+```
+
 ### Suppress a user
 
 Deletes the customer with the provided id if it exists and suppresses all future events and identifies for that customer.
@@ -261,6 +323,35 @@ Start tracking events and identifies again for a previously suppressed customer.
 $customerio.unsuppress(5)
 ```
 
+### Batch operations
+
+You can send up to 500KB of operations in a single request using the [Track v2 batch endpoint](https://customer.io/docs/api/track/#tag/Track-v2/operation/batch). Each operation can identify, track events, or delete people and objects.
+
+```ruby
+$customerio.batch([
+  {
+    type: "person",
+    identifiers: { id: "42" },
+    action: "identify",
+    attributes: { first_name: "Jane", plan: "premium" },
+  },
+  {
+    type: "person",
+    identifiers: { id: "42" },
+    action: "event",
+    name: "purchase",
+    data: { amount: 99 },
+  },
+  {
+    type: "person",
+    identifiers: { id: "99" },
+    action: "delete",
+  },
+])
+```
+
+See the [Track v2 API docs](https://customer.io/docs/api/track/#tag/Track-v2/operation/batch) for the full list of supported actions and fields.
+
 ### Send Transactional Messages
 
 To use the Customer.io [Transactional API](https://customer.io/docs/transactional-api), create an instance of the API client using an [app key](https://customer.io/docs/managing-credentials#app-api-keys) and create a request object of your message type.
@@ -271,7 +362,7 @@ Create a new `SendEmailRequest` object containing:
 
 * `transactional_message_id`: the ID of the transactional message you want to send, or the `body`, `from`, and `subject` of a new message.
 * `to`: the email address of your recipients 
-* an `identifiers` object containing the `id` of your recipient. If the `id` does not exist, Customer.io creates it.
+* an `identifiers` object containing the `email` and/or `id` of your recipient. If the person you reference by email or ID does not exist, Customer.io creates them.
 * a `message_data` object containing properties that you want reference in your message using liquid.
 * You can also send attachments with your message. Use `attach` to encode attachments.
 
@@ -295,7 +386,7 @@ request = Customerio::SendEmailRequest.new(
     products: [],
   },
   identifiers: {
-    id: "2",
+    email: "person@example.com",
   },
 )
 
@@ -348,11 +439,52 @@ rescue Customerio::InvalidResponse => e
 end
 ```
 
+### Trigger Broadcasts
+
+You can trigger [API-triggered broadcasts](https://customer.io/docs/api-triggered-broadcasts/) using the `APIClient`. Create a `TriggerBroadcastRequest` with the broadcast's numeric ID and optional audience/data parameters.
+
+```ruby
+require "customerio"
+
+client = Customerio::APIClient.new("your API key", region: Customerio::Regions::US)
+
+request = Customerio::TriggerBroadcastRequest.new(
+  broadcast_id: 12,
+  emails: ["recipient@example.com"],
+  data: {
+    headline: "Roadrunner spotted in Albuquerque!",
+    date: 1511315635,
+  },
+  email_add_duplicates: false,
+  email_ignore_missing: false,
+  id_ignore_missing: false,
+)
+
+begin
+  response = client.trigger_broadcast(request)
+  puts response
+rescue Customerio::InvalidResponse => e
+  puts e.code, e.message
+end
+```
+
+You can target the broadcast audience in several ways. Only one audience option can be present per request:
+
+- `recipients`: a hash with filter conditions (e.g., `{ segment: { id: 7 } }`)
+- `emails`: an array of email addresses
+- `ids`: an array of customer IDs
+- `per_user_data`: an array of per-user objects
+- `data_file_url`: a URL to a JSON lines file
+
+If you omit the audience option, the broadcast uses its default audience configured in the UI.
+
 ## Contributing
 
 1. Fork it
 2. Clone your fork (`git clone git@github.com:MY_USERNAME/customerio-ruby.git && cd customerio-ruby`)
 3. Create your feature branch (`git checkout -b my-new-feature`)
-4. Commit your changes (`git commit -am 'Added some feature'`)
-5. Push to the branch (`git push origin my-new-feature`)
-6. Create new Pull Request
+4. Install dependencies (`bundle install`)
+5. Run the test and lint suite (`bundle exec rake`)
+6. Commit your changes (`git commit -am 'Added some feature'`)
+7. Push to the branch (`git push origin my-new-feature`)
+8. Create new Pull Request

data/lib/customerio/api.rb

@@ -1,92 +1,78 @@
-require 'net/http'
-require 'multi_json'
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
 
 module Customerio
   class APIClient
     def initialize(app_key, options = {})
-      options[:region] = Customerio::Regions::US if options[:region].nil?
-      raise "region must be an instance of Customerio::Regions::Region" unless options[:region].is_a?(Customerio::Regions::Region)
+      options = options.dup
+      options[:region] = Regions::US if options[:region].nil?
+      unless options[:region].is_a?(Regions::Region)
+        raise ArgumentError, "region must be an instance of Customerio::Regions::Region"
+      end
 
       options[:url] = options[:region].api_url if options[:url].nil? || options[:url].empty?
-      @client = Customerio::BaseClient.new({ app_key: app_key }, options)
+      @client = BaseClient.new({ app_key: app_key }, options)
     end
 
     def send_email(req)
-      raise "request must be an instance of Customerio::SendEmailRequest" unless req.is_a?(Customerio::SendEmailRequest)
-      response = @client.request(:post, send_email_path, req.message)
+      validate_request!(req, SendEmailRequest)
 
-      case response
-      when Net::HTTPSuccess then
-        JSON.parse(response.body)
-      when Net::HTTPBadRequest then
-        json = JSON.parse(response.body)
-        raise Customerio::InvalidResponse.new(response.code, json['meta']['error'], response)
-      else
-        raise InvalidResponse.new(response.code, response.body)
-      end
+      deliver(send_email_path, req.message)
     end
 
     def send_push(req)
-      raise "request must be an instance of Customerio::SendPushRequest" unless req.is_a?(Customerio::SendPushRequest)
-      response = @client.request(:post, send_push_path, req.message)
+      validate_request!(req, SendPushRequest)
 
-      case response
-      when Net::HTTPSuccess then
-        JSON.parse(response.body)
-      when Net::HTTPBadRequest then
-        json = JSON.parse(response.body)
-        raise Customerio::InvalidResponse.new(response.code, json['meta']['error'], response)
-      else
-        raise InvalidResponse.new(response.code, response.body)
-      end
+      deliver(send_push_path, req.message)
     end
 
     def send_sms(req)
-      raise "request must be an instance of Customerio::SendSMSRequest" unless req.is_a?(Customerio::SendSMSRequest)
-      response = @client.request(:post, send_sms_path, req.message)
+      validate_request!(req, SendSMSRequest)
 
-      case response
-      when Net::HTTPSuccess then
-        JSON.parse(response.body)
-      when Net::HTTPBadRequest then
-        json = JSON.parse(response.body)
-        raise Customerio::InvalidResponse.new(response.code, json['meta']['error'], response)
-      else
-        raise InvalidResponse.new(response.code, response.body)
-      end
+      deliver(send_sms_path, req.message)
     end
 
     def send_inbox_message(req)
-      raise "request must be an instance of Customerio::SendInboxMessageRequest" unless req.is_a?(Customerio::SendInboxMessageRequest)
-      response = @client.request(:post, send_inbox_message_path, req.message)
+      validate_request!(req, SendInboxMessageRequest)
 
-      case response
-      when Net::HTTPSuccess then
-        JSON.parse(response.body)
-      when Net::HTTPBadRequest then
-        json = JSON.parse(response.body)
-        raise Customerio::InvalidResponse.new(response.code, json['meta']['error'], response)
-      else
-        raise InvalidResponse.new(response.code, response.body)
-      end
+      deliver(send_inbox_message_path, req.message)
     end
 
     def send_in_app(req)
-      raise "request must be an instance of Customerio::SendInAppRequest" unless req.is_a?(Customerio::SendInAppRequest)
-      response = @client.request(:post, send_in_app_path, req.message)
+      validate_request!(req, SendInAppRequest)
+
+      deliver(send_in_app_path, req.message)
+    end
+
+    def trigger_broadcast(req)
+      validate_request!(req, TriggerBroadcastRequest)
+
+      deliver(trigger_broadcast_path(req.broadcast_id), req.message)
+    end
+
+    private
+
+    def deliver(path, message)
+      response = @client.request(:post, path, message)
 
       case response
-      when Net::HTTPSuccess then
+      when Net::HTTPSuccess
         JSON.parse(response.body)
-      when Net::HTTPBadRequest then
-        json = JSON.parse(response.body)
-        raise Customerio::InvalidResponse.new(response.code, json['meta']['error'], response)
+      when Net::HTTPBadRequest
+        error = JSON.parse(response.body).dig("meta", "error")
+        raise InvalidResponse.new(response.code, error, response)
       else
-        raise InvalidResponse.new(response.code, response.body)
+        raise InvalidResponse.new(response.code, response.body, response)
       end
     end
 
-    private
+    def validate_request!(request, request_class)
+      return if request.is_a?(request_class)
+
+      raise ArgumentError, "request must be an instance of #{request_class}"
+    end
 
     def send_email_path
       "/v1/send/email"
@@ -107,5 +93,9 @@ module Customerio
     def send_in_app_path
       "/v1/send/in_app"
     end
+
+    def trigger_broadcast_path(broadcast_id)
+      "/v1/campaigns/#{broadcast_id}/triggers"
+    end
   end
 end

data/lib/customerio/base_client.rb

@@ -1,19 +1,22 @@
-require 'net/http'
-require 'multi_json'
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
 
 module Customerio
-  DEFAULT_TIMEOUT  = 10
+  DEFAULT_TIMEOUT = 10
+
+  class InvalidRequest < StandardError; end
 
-  class InvalidRequest < RuntimeError; end
-  class InvalidResponse < RuntimeError
+  class InvalidResponse < StandardError
     attr_reader :code, :response
 
-    def initialize(code, body, response=nil)
-      @message = body
+    def initialize(code, body, response = nil)
       @code = code
       @response = response
 
-      super(@message)
+      super(body)
     end
   end
 
@@ -36,27 +39,28 @@ module Customerio
 
     def execute(method, path, body = nil, headers = {})
       uri = URI.join(@base_uri, path)
+      request_headers = headers.dup
 
       session = Net::HTTP.new(uri.host, uri.port)
-      session.use_ssl = (uri.scheme == 'https')
+      session.use_ssl = uri.scheme == "https"
       session.open_timeout = @timeout
       session.read_timeout = @timeout
 
-      req = request_class(method).new(uri.path)
+      req = request_class(method).new(uri.request_uri)
 
-      headers['User-Agent'] = "Customer.io Ruby Client/" + Customerio::VERSION
+      request_headers["User-Agent"] = "Customer.io Ruby Client/#{VERSION}"
 
-      if @auth.has_key?(:site_id) && @auth.has_key?(:api_key)
-        req.initialize_http_header(headers)
+      if @auth.key?(:site_id) && @auth.key?(:api_key)
+        req.initialize_http_header(request_headers)
         req.basic_auth @auth[:site_id], @auth[:api_key]
       else
-        headers['Authorization'] = "Bearer #{@auth[:app_key]}"
-        req.initialize_http_header(headers)
+        request_headers["Authorization"] = "Bearer #{@auth[:app_key]}"
+        req.initialize_http_header(request_headers)
       end
 
-      if !body.nil?
-        req.add_field('Content-Type', 'application/json')
-        req.body = MultiJson.dump(body)
+      unless body.nil?
+        req.add_field("Content-Type", "application/json")
+        req.body = JSON.generate(body)
       end
 
       session.start do |http|
@@ -72,14 +76,16 @@ module Customerio
         Net::HTTP::Put
       when :delete
         Net::HTTP::Delete
+      when :get
+        Net::HTTP::Get
       else
-        raise InvalidRequest.new("Invalid request method #{method.inspect}")
+        raise InvalidRequest, "Invalid request method #{method.inspect}"
       end
     end
 
     def verify_response(response)
       case response
-      when Net::HTTPSuccess then
+      when Net::HTTPSuccess
         response
       else
         raise InvalidResponse.new(response.code, response.body, response)