{"id":26163489,"url":"https://github.com/starburstgem/starburst","last_synced_at":"2025-04-10T01:06:55.036Z","repository":{"id":21483947,"uuid":"24802725","full_name":"starburstgem/starburst","owner":"starburstgem","description":"In-app announcements to users in your Rails app","archived":false,"fork":false,"pushed_at":"2023-04-28T16:41:19.000Z","size":366,"stargazers_count":258,"open_issues_count":21,"forks_count":29,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-10T01:06:48.237Z","etag":null,"topics":["announcement","rails","ruby","scheduling"],"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/starburstgem.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":null,"security":null,"support":null,"governance":null}},"created_at":"2014-10-04T21:58:27.000Z","updated_at":"2024-09-15T12:04:16.000Z","dependencies_parsed_at":"2023-07-22T06:37:59.927Z","dependency_job_id":null,"html_url":"https://github.com/starburstgem/starburst","commit_stats":null,"previous_names":["csm123/starburst"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starburstgem%2Fstarburst","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starburstgem%2Fstarburst/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starburstgem%2Fstarburst/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starburstgem%2Fstarburst/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/starburstgem","download_url":"https://codeload.github.com/starburstgem/starburst/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137887,"owners_count":21053775,"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":["announcement","rails","ruby","scheduling"],"created_at":"2025-03-11T14:27:20.964Z","updated_at":"2025-04-10T01:06:55.013Z","avatar_url":"https://github.com/starburstgem.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Starburst\n\n[![Build Status](https://travis-ci.org/starburstgem/starburst.svg?branch=master)](https://travis-ci.org/starburstgem/starburst)\n[![Maintainability](https://api.codeclimate.com/v1/badges/7f5df24aaefecbd270b4/maintainability)](https://codeclimate.com/github/starburstgem/starburst/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/7f5df24aaefecbd270b4/test_coverage)](https://codeclimate.com/github/starburstgem/starburst/test_coverage)\n\nStarburst allows you to show messages to logged in users within your Rails app. Once the user closes the message, they won't see it again.\n\nYou can target messages to particular groups of users, based on their database attributes or your own methods on the `User` class. For instance, you might send a message only to users on your premium plan.\n\nStarburst remembers _on the server_ who has closed which message. Therefore, a user who closes a message on their desktop won't see it again on their mobile device. Starburst doesn't use cookies, so a user won't see an announcement they've already read if they switch devices or clear their cookies.\n\nStarburst is in production on [Cook Smarts](https://www.cooksmarts.com), where it has served announcements to thousands of users.\n\n[![Announcement in ZURB Foundation](http://aspiringwebdev.com/wp-content/uploads/2014/10/starburst-foundation.png)](#)\n\n_An announcement delivered by Starburst, on a Rails app using ZURB Foundation_\n\n## Use cases\n\nUse Starburst to share announcements with your users, like:\n\n- A new feature\n- Upcoming downtime\n- A coupon to upgrade to a premium plan\n\nUsers will see the message until they dismiss it, and then won't see it again.\n\nA user will not see the next announcement until they acknowledge the previous one (i.e. users are shown one announcement at a time). Announcements are delivered earliest first. Be sure to [schedule](#scheduling-announcements) announcements so they appear only while they're relevant.\n\n## Requirements\n\n### Authentication\nStarburst needs to know who is logged in to your app. If you are using [Devise](https://github.com/heartcombo/devise), [Clearance](https://github.com/thoughtbot/clearance), or another authentication library that sets a `current_user` method, you're all set.\n\nIf you use a different authentication system that does not set a `current_user` method, [tell Starburst](#current-user) what method your library uses.\n\n### Ruby and Rails\n\nStarburst [works](https://secure.travis-ci.org/starburstgem/starburst) on Rails 4.2, 5.0, 5.1, 5.2, 6.0, and 6.1. It should work with the same Ruby runtime versions supported by each framework version.\n\n## Installation\n\nAdd Starburst to your `Gemfile`:\n\n```ruby\ngem 'starburst'\n```\n\nMigrate your database:\n\n```sh\n$ rake starburst:install:migrations\n$ rake db:migrate\n```\n\nAdd the following line to your `ApplicationController`:\n\n```ruby\nhelper Starburst::AnnouncementsHelper\n```\n\nAdd the following line to your routes file:\n\n```ruby\nmount Starburst::Engine =\u003e '/starburst'\n```\n\nAdd the following line to your `application.js` file:\n\n```javascript\n//= require starburst/starburst\n```\n\n## Getting started\n\n### Add an announcement partial to your app's layout\n\nStarburst comes with pre-built announcement boxes for sites using [ZURB Foundation](https://get.foundation) and [Bootstrap](https://getbootstrap.com). It also includes an announcement box with no assigned styles.\n\nAdd one of the lines below your application layout view at `app/views/layouts/application.html.erb`, right above `\u003c%= yield =\u003e`. You can place the partials anywhere, of course; this is just the most common location.\n\n#### Bootstrap\n\n```erb\n\u003c%= render partial: 'announcements/starburst/announcement_bootstrap' %\u003e\n```\n\n#### ZURB Foundation\n\n```erb\n\u003c%= render partial: 'announcements/starburst/announcement_foundation' %\u003e\n```\n\n#### Custom styles\n\n```erb\n\u003c%= render partial: 'announcements/starburst/announcement' %\u003e\n```\n\nSet your own styles. Use `#starburst-announcement` ID for the box, and the `#starburst-close` for the close button.\n\n### Add an announcement\n\nStarburst doesn't have an admin interface yet, but you can add announcements through your own code.\n\n```ruby\nStarburst::Announcement.create(body: 'Our app now features lots of balloons! Enjoy!')\n```\n\nThis will present an announcement to every user of the app. Once they dismiss the announcement, they won't see it again.\n\nFind out more about [scheduling announcements](#scheduling-announcements) and [targeting them to specific users](#targeting-announcements).\n\n## Scheduling announcements\n\nYou can schedule announcements as follows:\n\n`start_delivering_at` - Do not deliver this announcement until this date.\n\n`stop_delivering_at` - Do not show this announcement to anyone after this date, not even to users who have seen the message before but not acknowledged it.\n\n```ruby\nStarburst::Announcement.create(\n  body: 'Our app now features lots of balloons! Enjoy!',\n  start_delivering_at: Date.current,\n  stop_delivering_at: Date.current.advance(days: 10)\n)\n```\n\n## Targeting announcements\n\nYou can target announcements to particular users by setting the `limit_to_users` option.\n\nThe code below targets the announcement to users with a `subscription` field equal to `gold`.\n\n```ruby\nStarburst::Announcement.create(\n  body: '\u003ca href=\"/upgrade\"\u003eUpgrade to platinum\u003c/a\u003e and save 10% with coupon code XYZ!',\n  limit_to_users: [\n    {\n      field: 'subscription',\n      value: 'gold'\n    }\n  ]\n)\n```\n\n## Advanced configuration\n\n### Base controller\n\nBy default, `Starburst::AnnouncementsController` will inherit from `ApplicationController`. If you need to change that setting in order to have access to the configured `current_user_method`, just change the `base_controller` setting:\n\n```ruby\nStarburst.configuration do |config|\n  config.base_controller = 'AuthenticatedController'\nend\n```\n\n### Current user\n\nMost Rails authentication libraries (like Devise and Clearance) place the current user into the `current_user` method. If your authentication library uses a different method, create an initializer file for Starburst at `config/initializers/starburst.rb` and add the code below, replacing `current_user` with the name of the equivalent method in your authentication library.\n\n```ruby\nStarburst.configuration do |config|\n  config.current_user_method = :current_user\nend\n```\n\n### Targeting by methods rather than fields\n\nWith targeting, you can limit which users will see a particular announcement. Out of the box, Starburst allows you to limit by fields in the database. However, your `User` model may have methods that don't directly map to database fields.\n\nFor instance, your `User` model might have an instance method `free?` that returns `true` if the user is on a free plan and `false` if they are on a paid plan. The actual field in the database may be called something different.\n\nYou can target based on methods that are not in the database, but you must specify those methods in a Starburst initializer. Create an initializer for Starburst at `config/initializers/starburst.rb` and add the code below:\n\n```ruby\nStarburst.configuration do |config|\n  config.user_instance_methods = %i[free?]\nend\n```\n\n`user_instance_methods` is an array, so you can specify more than one method. All of the methods will be available for [targeting](#targeting-announcements), as if they were fields.\n\n## Upgrading\n\n### From 0.9.x to 1.0\n\nThis guidance applies only to users of Starburst who are upgrading from 0.9.x to 1.0.\n\n**IMPORTANT**: This version introduces a uniqueness constraint on the `AnnouncementView` table. Before installing, you must find and clear out duplicate announcement views in the table:\n\n1. In console on both the development and production environments, run this to find duplicate announcement views:\n```ruby\nStarburst::AnnouncementView.select(%i[announcement_id user_id]).group(:announcement_id, :user_id).having('COUNT(*) \u003e 1').count\n```\n2. Delete duplicate announcement views as necessary so you have only one of each. Use the `destroy` method on each individual view\n3. Run `rake starburst:install:migrations` and then `rake db:migrate` on your development environment, then push to production\n\n## Contributors\n\nThanks to [@jhenkens](https://github.com/jhenkens) for fixes, performance improvements, and ideas for showing announcements to non-logged-in users.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarburstgem%2Fstarburst","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarburstgem%2Fstarburst","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarburstgem%2Fstarburst/lists"}