{"id":23276167,"url":"https://github.com/mikamai/onesignal-ruby","last_synced_at":"2025-04-07T09:18:10.123Z","repository":{"id":33968377,"uuid":"139002399","full_name":"mikamai/onesignal-ruby","owner":"mikamai","description":"A simple, pure Ruby client to the OneSignal Push Notification API","archived":false,"fork":false,"pushed_at":"2023-04-26T10:28:34.000Z","size":172,"stargazers_count":35,"open_issues_count":7,"forks_count":53,"subscribers_count":12,"default_branch":"develop","last_synced_at":"2025-03-31T07:06:14.748Z","etag":null,"topics":["gem","onesignal","ruby"],"latest_commit_sha":null,"homepage":"","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/mikamai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-28T10:18:05.000Z","updated_at":"2025-02-19T14:44:06.000Z","dependencies_parsed_at":"2024-06-21T15:21:48.600Z","dependency_job_id":"19915d21-8245-41e9-8034-b7281bf0651d","html_url":"https://github.com/mikamai/onesignal-ruby","commit_stats":{"total_commits":133,"total_committers":19,"mean_commits":7.0,"dds":0.5563909774436091,"last_synced_commit":"9890d29d27d6ae4245dd89ed20d509d6a9904f46"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikamai%2Fonesignal-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikamai%2Fonesignal-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikamai%2Fonesignal-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikamai%2Fonesignal-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikamai","download_url":"https://codeload.github.com/mikamai/onesignal-ruby/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622985,"owners_count":20968575,"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":["gem","onesignal","ruby"],"created_at":"2024-12-19T21:29:30.975Z","updated_at":"2025-04-07T09:18:10.102Z","avatar_url":"https://github.com/mikamai.png","language":"Ruby","readme":"# OneSignal Ruby Client\n[![Gem Version](https://badge.fury.io/rb/onesignal-ruby.svg)](https://badge.fury.io/rb/onesignal-ruby)\n[![CircleCI](https://circleci.com/gh/mikamai/onesignal-ruby.svg?style=svg)](https://circleci.com/gh/mikamai/onesignal-ruby)\n\nA simple, pure Ruby client to the [OneSignal Push Notification API](https://onesignal.com/). OneSignal provides a self-serve customer engagement solution for Push Notifications, Email, SMS \u0026 In-App.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'onesignal-ruby'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install onesignal-ruby\n\n## Configuration\nOneSignal requires an App ID and an API Key, which can be found\non the OneSignal dashboard.\nBy default, OneSignal Ruby looks for them in the environment, loading\n`ONESIGNAL_APP_ID` and `ONESIGNAL_API_KEY` variables.\n\nIt also defaults to `https://onesignal.com/api/v1` as the API URL.\n\nYou can also turn off OneSignal entirely with a boolean flag (for example to avoid sending\nnotification while in test or development environments)\n\nIt will also use an internal instance of the Ruby Logger at `INFO` level.\n\nTo customize those values, call the following snippet during your\ninitialization phase.\n\n```ruby\nrequire 'onesignal'\n\nOneSignal.configure do |config|\n  config.app_id = 'my_app_id'\n  config.api_key = 'my_api_key'\n  config.api_url = 'http://my_api_url'\n  config.active = false\n  config.logger = Logger.new # Any Logger compliant implementation\nend\n```\n## Usage\n\n### Create a notification\n\nCreate a `Notification` object.\n```ruby\n# Create headings for different languages. English is required.\nheadings = OneSignal::Notification::Headings.new(en: 'Hello!', it: 'Ciao!')\n\n# Create contents for different languages. English is required.\ncontents = OneSignal::Notification::Contents.new(en: \"I'm a notification!\", it: 'Sono una notifica!')\n\n# Select the included (and/or excluded) segments to target\nincluded_segments = [OneSignal::Segment::ACTIVE_USERS, 'My custom segment']\n\n# Create the Notification object\nnotification = OneSignal::Notification.new(headings: headings, contents: contents, included_segments: included_segments)\n```\n\nThen send it.\n```ruby\n response = OneSignal.send_notification(notification)\n # =\u003e #\u003cOneSignal::Responses::Notification\u003e the created notification\n```\n\n### Fetch a notification\nYou can fetch an existing notification given its ID.\n```ruby\nresponse = OneSignal.fetch_notification(notification_id)\n# =\u003e #\u003cOneSignal::Responses::Notification\u003e the created notification\n```\n`OneSignal::Responses::Notification` has the following fields.\n```ruby\nid            # Notification UUID\nsuccessful    # Number of successful deliveries\nfailed        # Number of failed deliveries\nconverted     # Number of users who have clicked / tapped on your notification.\nremaining     # Number of notifications that have not been sent out yet\nqueued_at     # Unix timestamp of enqueuing time\nsend_after    # Unix timestamp indicating when notification delivery should begin\ncompleted_at  # Unix timestamp indicating when notification delivery completed.\nurl           # URL associated with the notification\ndata          # Custom metadata\ncanceled      # Boolean, has the notification been canceled\nheadings      # Map of locales to title strings\ncontents      # Map of locales to content strings\n\nresponse.id # =\u003e fe82c1ae-54c2-458b-8aad-7edc3e8a96c4\n```\n\n### Attachments\nYou can add files, data or images to a notification, or an external URL to open.\n```ruby\nattachments = OneSignal::Attachments.new(\n      data:            { 'test' =\u003e 'test' },\n      url:             'http://example.com',\n      ios_attachments: { 'something' =\u003e 'drawable resource name or URL.' },\n      android_picture: 'drawable resource name or URL.',\n      amazon_picture:  'drawable resource name or URL.',\n      chrome_picture:  'drawable resource name or URL.'\n)\n\nOneSignal::Notification.new(attachments: attachments)\n```\n\n### Buttons\nYou can add interactive buttons to a notification. See https://documentation.onesignal.com/docs/action-buttons for more details.\n\n```ruby\nbuttons = OneSignal::Buttons.new(\n    buttons: [{id: 'option_a', text: 'Option A' }, {id: 'option_b', text: 'Option B' }]\n)\n\nOneSignal::Notification.new(buttons: buttons)\n```\n\n### Fetch players\nYou can fetch all players and devices with a simple method.\n\n```ruby\nplayers = OneSignal.fetch_players\n# =\u003e Array of OneSignal::Responses::Player\n```\n\nOr you can fetch a single player by its ID.\n```ruby\nplayer = OneSignal.fetch_player(player_id)\n# =\u003e #\u003cOneSignal::Responses::Player\u003e\n```\n\n### Delete players\nYou can delete a single player by its ID.\n```ruby\nOneSignal.delete_player(player_id)\n#\u003cOneSignal::Responses::Player:0x000056062f397d18 @attributes={}\u003e\n```\n\n### Filters\n\nFilters can be created with a simple DSL. It closely matches the [JSON reference](https://documentation.onesignal.com/reference#section-send-to-users-based-on-filters), with a few touches of syntax\nsugar.\n\n**Example**\n```ruby\nfilters = [\n  OneSignal::Filter.last_session.lesser_than(2).hours_ago!,\n  OneSignal::Filter.session_count.equals(5),\n  OneSignal::Filter::OR,\n  OneSignal::Filter.country.equals('IT')\n]\n\nOneSignal::Notification.new(filters: filters)\n```\nBecomes\n```json\n[\n  {\"field\":\"last_session\",\"relation\":\"\u003c\",\"hours_ago\":\"2\"},\n  {\"field\":\"session_count\",\"relation\":\"=\",\"value\":\"5\"},\n  {\"operator\":\"OR\"},\n  {\"field\":\"country\",\"relation\":\"=\",\"value\":\"IT\"}\n]\n```\n\nThe operator methods (`#lesser_than`, `#greater_than`, `#equals`, `#not_equals`) are also available through the following shorthands: `\u003c`, `\u003e`, `=`, `!=`.\n\n**Example**\n```ruby\nfilters = [\n  OneSignal::Filter.tag('userId') == 5,\n  OneSignal::Filter.session_count \u003c 2,\n  OneSignal::Filter.language != 'en'\n]\n\nOneSignal::Notification.new(filters: filters)\n```\n\n### Custom Sounds\nYou can customize notification sounds by passing a `OneSignal::Sounds` object.\n```ruby\nsounds = OneSignal::Sounds.new(ios: 'ping.wav', android: 'ping')\nOneSignal::Notification.new(sounds: sounds)\n```\n\n### Specific Targets\nIf you want to send a notification only to specific targets (a particular user's email or device) you can\npass a `OneSignal::IncludedTargets` to the notification object.\nSee [the official documentation](https://documentation.onesignal.com/reference#section-send-to-specific-devices) for a list of available params.\n```ruby\nincluded_targets = OneSignal::IncludedTargets.new(include_player_ids: ['test-id-12345'])\nOneSignal::Notification.new(included_targets: included_targets)\n```\n\n### Icons\nYou can customize notification icons by passing a `OneSignal::Icons` object.\n```ruby\nicons = OneSignal::Icons.new(\n  small_icon: 'image URL',\n  huawei_small_icon: 'image URL',\n  large_icon: 'image URL',\n  huawei_large_icon: 'image URL',\n  adm_small_icon: 'image URL',\n  adm_large_icon: 'image URL',\n  chrome_web_icon: 'image URL',\n  firefox_icon: 'image URL',\n  chrome_icon: 'image URL'\n)\nOneSignal::Notification.new(icons: icons)\n```\n\n**WARNING**\nPassing `include_player_ids` alongside other params is prohibited and will raise an `ArgumentError`.\nEither use `include_player_ids` or use the other params.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/mikamai/onesignal-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\nThis repo is managed following the [Git Flow](https://danielkummer.github.io/git-flow-cheatsheet/) principles.\n- `master` is the stable, production-ready branch. Never work directly on it. The gem is published from this branch.\n- `develop` is the active development branch. It is supposed to be somewhat stable. Every new feature is merged here once completed, before being released to master.\n- `feature/my-awesome-branch` are personal, dedicated branches for working on actual features. They are merged in develop once completed and then deleted.\n- `hotfix/my-awesome-fix` are special branches dedicated to bugfixes that compromise the library functionality. They are merged\nin both master and develop and then deleted.\n\n[CHANGELOG](CHANGELOG.md) entries MUST be added for every change made to the source code.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the OneSignal Ruby project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikamai%2Fonesignal-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikamai%2Fonesignal-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikamai%2Fonesignal-ruby/lists"}