{"id":21414673,"url":"https://github.com/customerio/customerio-ruby","last_synced_at":"2025-05-15T08:04:52.769Z","repository":{"id":3362825,"uuid":"4408794","full_name":"customerio/customerio-ruby","owner":"customerio","description":"A ruby client for the Customer.io event API.","archived":false,"fork":false,"pushed_at":"2025-04-02T14:27:17.000Z","size":144,"stargazers_count":65,"open_issues_count":23,"forks_count":76,"subscribers_count":33,"default_branch":"main","last_synced_at":"2025-05-07T23:43:32.217Z","etag":null,"topics":["customerio","ruby"],"latest_commit_sha":null,"homepage":"https://customer.io/docs/api/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/customerio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.markdown","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-05-22T15:31:35.000Z","updated_at":"2025-04-02T14:27:25.000Z","dependencies_parsed_at":"2025-04-13T09:15:33.815Z","dependency_job_id":null,"html_url":"https://github.com/customerio/customerio-ruby","commit_stats":{"total_commits":143,"total_committers":32,"mean_commits":4.46875,"dds":0.7132867132867133,"last_synced_commit":"377744c2542ff963d3c55b10283d1b7a0c479b39"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/customerio%2Fcustomerio-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/customerio%2Fcustomerio-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/customerio%2Fcustomerio-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/customerio%2Fcustomerio-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/customerio","download_url":"https://codeload.github.com/customerio/customerio-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301422,"owners_count":22047901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["customerio","ruby"],"created_at":"2024-11-22T18:32:27.963Z","updated_at":"2025-05-15T08:04:52.715Z","avatar_url":"https://github.com/customerio.png","language":"Ruby","readme":"\u003cp align=center\u003e\n  \u003ca href=\"https://customer.io\"\u003e\n    \u003cimg src=\"https://avatars.githubusercontent.com/u/1152079?s=200\u0026v=4\" height=\"60\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n[![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/)\n[![ci](https://github.com/customerio/customerio-ruby/actions/workflows/main.yml/badge.svg)](https://github.com/customerio/customerio-ruby/actions/workflows/main.yml)\n\n# Customer.io Ruby \n\nA ruby client for the [Customer.io Journeys Track API](https://customer.io/docs/api/track/).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'customerio'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself:\n\n    $ gem install customerio\n\n## Usage\n\n### Before we get started: API client vs. JavaScript snippet\n\nIt's helpful to know that everything below can also be accomplished\nthrough the [Customer.io JavaScript snippet](https://customer.io/docs/javascript-quick-start/).\n\nIn many cases, using the JavaScript snippet will be easier to integrate with\nyour app, but there are several reasons why using the API client is useful:\n\n* You're not planning on triggering emails based on how customers interact with\n  your website (e.g. users who haven't visited the site in X days)\n* You're using the javascript snippet, but have a few events you'd like to\n  send from your backend system.  They will work well together!\n* You'd rather not have another javascript snippet slowing down your frontend.\n  Our snippet is asynchronous (doesn't affect initial page load) and very small, but we understand.\n\nIn the end, the decision on whether or not to use the API client or\nthe JavaScript snippet should be based on what works best for you.\nYou'll be able to integrate **fully** with [Customer.io](https://customer.io) with either approach.\n\n### Setup\n\nCreate an instance of the client with your [Customer.io credentials](https://fly.customer.io/settings/api_credentials).\n\nIf you're using Rails, create an initializer `config/initializers/customerio.rb`:\n\n```ruby\n$customerio = Customerio::Client.new(\"YOUR SITE ID\", \"YOUR API SECRET KEY\", region: Customerio::Regions::US)\n```\n\n`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. \n\n### Identify logged in customers\n\nTracking data of logged in customers is a key part of [Customer.io](https://customer.io). In order to\nsend triggered emails, we must know the email address of the customer.  You can\nalso specify any number of customer attributes which help tailor [Customer.io](https://customer.io) to your\nbusiness.\n\nAttributes you specify are useful in several ways:\n\n* As customer variables in your triggered emails.  For instance, if you specify\nthe customer's name, you can personalize the triggered email by using it in the\nsubject or body.\n\n* As a way to filter who should receive a triggered email.  For instance,\nif you pass along the current subscription plan (free / basic / premium) for your customers, you can\nset up triggers which are only sent to customers who have subscribed to a\nparticular plan (e.g. \"premium\").\n\nYou'll want to identify your customers when they sign up for your app and any time their\nkey information changes. This keeps [Customer.io](https://customer.io) up to date with your customer information.\n\n```ruby\n# Arguments\n# attributes (required) - a hash of information about the customer. You can pass any\n#                         information that would be useful in your triggers. You \n#                         must at least pass in an id, email, and created_at timestamp.\n\n$customerio.identify(\n  :id =\u003e 5,\n  :email =\u003e \"bob@example.com\",\n  :created_at =\u003e customer.created_at.to_i,\n  :first_name =\u003e \"Bob\",\n  :plan =\u003e \"basic\"\n)\n```\n\n### Updating customers: Changing identifiers\n\nYou can use the identify operation to update customers.\nIf you need to change the `id` or `email` identifiers for a customer,\nyou will need to pass in the `cio_id` identifier.\n`cio_id` is a unique identifier set by Customer.io, used to reference a person,\nand cannot be changed.\n\nE.g.: if the customer created in the identify operation above was given the `cio_id` of `\"f000000d\"`, you could change its ID and email address using:\n\n```ruby\n$customerio.identify(\n  :cio_id =\u003e \"f000000d\",\n  :id =\u003e 1005,\n  :email =\u003e \"bob.fullname@example.com\"\n)\n```\n\nThis method requires either the `id` or `cio_id` for the person. It does not work with email addresses.\n\nYou can also use this method to make other updates to the person using the `cio_id`.\n\n### Updating customers: Using email address\n\nIf you need to identify a person using their email address, then you can do so\nby passing in a customer ID to the `identify` method. This allows you to specify\na customer ID that is different than the one used in the `id` attribute. E.g.:\n\n```ruby\n# Arguments\n# customer_id (required) - the customer ID to use for this customer, may be an id, email address, or the cio_id.\n#                         This will be used to construct the URL but not sent in the body attributes.\n# attributes (required) - a hash of information about the customer. You can pass any\n#                         information that would be useful in your triggers. You\n#                         must at least pass in an id, email, and created_at timestamp.\n\n$customerio.identify(\n  :customer_id =\u003e \"bob@example.com\",\n  :location =\u003e \"Australia\"\n)\n```\n\nNote:\n\n * If you want to use the `cio_id` in the `customer_id` field of `identify_customer_id`, you will need to prefix it with `\"cio_\"`. E.g.: `\"cio_f000000d\"` for a `cio_id` of `f000000d`.\n * The `identify` method can identify the person using one of `customer_id`, `cio_id` or `id`. The order of precedence is `customer_id` \u003e `cio_id` \u003e `id`.\n\n### Deleting customers\n\nDeleting a customer will remove them, and all their information from\nCustomer.io.  Note: if you're still sending data to Customer.io via\nother means (such as the javascript snippet), the customer could be\nrecreated.\n\n```ruby\n# Arguments\n# customer_id (required) - a unique identifier for the customer.  This\n#                          should be the same id you'd pass into the\n#                          `identify` command above.\n\n$customerio.delete(5)\n```\n\n### Merge duplicate customer profiles\n\nWhen you merge two people, you pick a primary person and merge a secondary, duplicate person into it. The primary person remains after the merge and the secondary is deleted. This process is permanent: you cannot recover the secondary person.\n\nThe first and third parameters represent the identifier for the primary and secondary people respectively—one of `id`, `email`, or `cio_id`. The second and fourth parameters are the identifier values for the primary and secondary people respectively.\n\n```ruby\n# $customerio.merge_customers(\"primaryType\", \"primaryIdentifier\", \"secondaryType\", \"secondaryIdentifier\")\n# primaryType / secondaryType are one of \"id\", \"email\", or \"cio_id\"\n# primaryIdentifier / secondaryIdentifier are the identifier value corresponding to the type.\n\n# merge customer \"cperson@gmail.com\" into \"cool.person@company.com\"\n$customerio.merge_customers(\"email\", \"cool.person@company.com\", \"email\", \"cperson@gmail.com\")\n```\n\n### Tracking a custom event\n\nNow that you're identifying your customers with [Customer.io](https://customer.io), you can now send events like\n\"purchased\" or \"watchedIntroVideo\".  These allow you to more specifically target your users\nwith automated emails, and track conversions when you're sending automated emails to\nencourage your customers to perform an action.\n\n```ruby\n# Arguments\n# customer_id (required) - the id of the customer who you want to associate with the event.\n# name (required)        - the name of the event you want to track.\n# attributes (optional)  - any related information you'd like to attach to this\n#                          event. These attributes can be used in your triggers to control who should\n#                          receive the triggered email. You can set any number of data values.\n\n$customerio.track(5, \"purchase\", :type =\u003e \"socks\", :price =\u003e \"13.99\")\n```\n\n**Note:** If you want to track events which occurred in the past, you can include a `timestamp` attribute\n(in seconds since the epoch), and we'll use that as the date the event occurred.\n\n```ruby\n$customerio.track(5, \"purchase\", :type =\u003e \"socks\", :price =\u003e \"13.99\", :timestamp =\u003e 1365436200)\n```\n\n### Tracking anonymous events\n\nYou can also send anonymous events, for situations where you don't yet have a customer record yet. An anonymous event requires an `anonymous_id` representing the unknown person and an event `name`. When you identify a person, you can set their `anonymous_id` attribute. If [event merging](https://customer.io/docs/anonymous-events/#turn-on-merging) is turned on in your workspace, and the attribute matches the `anonymous_id` in one or more events that were logged within the last 30 days, we associate those events with the person.\n\nAnonymous events cannot trigger campaigns by themselves. To trigger a campaign, the anonymous event must be associated with a person within 72 hours of the `track_anonymous` request.\n\n```ruby\n# Arguments\n# anonymous_id (required, nullable) - the id representing the unknown person.\n# name (required)                   - the name of the event you want to track.\n# attributes (optional)             - related information you want to attach to the event.\n\n$customerio.track_anonymous(anonymous_id, \"product_view\", :type =\u003e \"socks\" )\n```\n\nUse 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/).\n\n#### Anonymous invite events\n\nIf 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. \n\n```ruby\n$customerio.track_anonymous(nil, \"invite\", :recipient =\u003e \"new.person@example.com\" )\n```\n\n### Adding a mobile device\n\nTo send push notifications, you can add ios and android device tokens to a customer:\n\n```ruby\n$customerio.add_device(5, \"my_ios_device_id\", \"ios\")\n$customerio.add_device(5, \"my_android_device_id\", \"android\")\n```\n\nOptionally, `last_used` can be passed in to specify the last touch of the device. Otherwise, this attribute is set by the API.\n\n```ruby\n$customerio.add_device(5, \"my_ios_device_id\", \"ios\", {:last_used=\u003eTime.now.to_i})\n```\n\n### Removing a mobile device\n\nDeleting a device token will remove it from the associated customer to stop further push notifications from being sent for that device\n\n```ruby\n$customerio.delete_device(5, \"my_device_token\")\n```\n\n### Suppress a user\n\nDeletes the customer with the provided id if it exists and suppresses all future events and identifies for that customer.\n\n```ruby\n$customerio.suppress(5)\n```\n\n### Unsuppress a user\n\nStart tracking events and identifies again for a previously suppressed customer. Note when a user is suppressed thier history is deleted and unsupressing them wil not recover that history.\n\n```ruby\n$customerio.unsuppress(5)\n```\n\n### Send Transactional Messages\n\nTo 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.\n\n#### Email\n\nCreate a new `SendEmailRequest` object containing:\n\n* `transactional_message_id`: the ID of the transactional message you want to send, or the `body`, `from`, and `subject` of a new message.\n* `to`: the email address of your recipients \n* an `identifiers` object containing the `id` of your recipient. If the `id` does not exist, Customer.io creates it.\n* a `message_data` object containing properties that you want reference in your message using liquid.\n* You can also send attachments with your message. Use `attach` to encode attachments.\n\nUse `send_email` referencing your request to send a transactional message. [Learn more about transactional messages and `SendEmailRequest` properties](https://customer.io/docs/transactional-api).\n\n\n```ruby\nrequire \"customerio\"\n\nclient = Customerio::APIClient.new(\"your API key\", region: Customerio::Regions::US)\n\nrequest = Customerio::SendEmailRequest.new(\n  to: \"person@example.com\",\n  transactional_message_id: \"3\",\n  message_data: {\n    name: \"Person\",\n    items: {\n      name: \"shoes\",\n      price: \"59.99\",\n    },\n    products: [],\n  },\n  identifiers: {\n    id: \"2\",\n  },\n)\n\nfile = File.open('\u003cfile-path\u003e', 'r')\nrequest.attach(\"filename\", file.read)\n\nbegin\n  response = client.send_email(request)\n  puts response\nrescue Customerio::InvalidResponse =\u003e e\n  puts e.code, e.message\nend\n```\n\n#### Push\n\nCreate a new `SendPushRequest` object containing:\n\n* `transactional_message_id`: the ID or trigger name of the transactional message you want to send.\n* an `identifiers` object containing the `id` or `email` of your recipient. If the profile does not exist, Customer.io creates it.\n\nUse `send_push` referencing your request to send a transactional message. [Learn more about transactional messages and `SendPushRequest` properties](https://customer.io/docs/transactional-api).\n\n\n```ruby\nrequire \"customerio\"\n\nclient = Customerio::APIClient.new(\"your API key\", region: Customerio::Regions::US)\n\nrequest = Customerio::SendPushRequest.new(\n  transactional_message_id: \"3\",\n  message_data: {\n    name: \"Person\",\n    items: {\n      name: \"shoes\",\n      price: \"59.99\",\n    },\n    products: [],\n  },\n  identifiers: {\n    id: \"2\",\n  },\n)\n\nbegin\n  response = client.send_push(request)\n  puts response\nrescue Customerio::InvalidResponse =\u003e e\n  puts e.code, e.message\nend\n```\n\n## Contributing\n\n1. Fork it\n2. Clone your fork (`git clone git@github.com:MY_USERNAME/customerio-ruby.git \u0026\u0026 cd customerio-ruby`)\n3. Create your feature branch (`git checkout -b my-new-feature`)\n4. Commit your changes (`git commit -am 'Added some feature'`)\n5. Push to the branch (`git push origin my-new-feature`)\n6. Create new Pull Request\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcustomerio%2Fcustomerio-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcustomerio%2Fcustomerio-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcustomerio%2Fcustomerio-ruby/lists"}