{"id":13601965,"url":"https://github.com/nomad-cli/houston","last_synced_at":"2025-09-28T23:30:47.056Z","repository":{"id":4580638,"uuid":"5722466","full_name":"nomad-cli/houston","owner":"nomad-cli","description":"Apple Push Notifications; No Dirigible Required","archived":true,"fork":false,"pushed_at":"2021-06-20T11:02:39.000Z","size":149,"stargazers_count":2936,"open_issues_count":0,"forks_count":229,"subscribers_count":78,"default_branch":"master","last_synced_at":"2024-06-23T04:56:30.222Z","etag":null,"topics":["apns","cli","houston","nomad","notifications","ruby"],"latest_commit_sha":null,"homepage":"http://nomad-cli.com","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/nomad-cli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-09-07T21:08:33.000Z","updated_at":"2024-05-31T13:24:29.000Z","dependencies_parsed_at":"2022-08-02T20:15:13.555Z","dependency_job_id":null,"html_url":"https://github.com/nomad-cli/houston","commit_stats":null,"previous_names":["nomad/houston","mattt/houston"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomad-cli%2Fhouston","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomad-cli%2Fhouston/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomad-cli%2Fhouston/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomad-cli%2Fhouston/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nomad-cli","download_url":"https://codeload.github.com/nomad-cli/houston/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234569805,"owners_count":18854133,"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":["apns","cli","houston","nomad","notifications","ruby"],"created_at":"2024-08-01T18:01:10.825Z","updated_at":"2025-09-28T23:30:41.773Z","avatar_url":"https://github.com/nomad-cli.png","language":"Ruby","readme":"![Houston](https://raw.github.com/nomad/nomad.github.io/assets/houston-banner.png)\n\n[![Travis](https://img.shields.io/travis/nomad/houston.svg)](https://travis-ci.org/nomad/houston)\n\n\u003e **Note**: This project is no longer being maintained. Houston supports only the legacy binary APNs protocol, which as of March 31, 2021 is no longer supported. Please migrate to an alternative library, such as [Apnotic](https://github.com/ostinelli/apnotic) to send push notifications using the new APNs2 protocol. \n\nPush Notifications don't have to be difficult.\n\nHouston is a simple gem for sending Apple Push Notifications. Pass your credentials, construct your message, and send it.\n\nIn a production application, you will probably want to schedule or queue notifications into a background job. Whether you're using [queue_classic](https://github.com/ryandotsmith/queue_classic), [resque](https://github.com/resque/resque), or rolling you own infrastructure, integrating Houston couldn't be simpler.\n\n\u003e Houston is named for [Houston, TX](http://en.wikipedia.org/wiki/Houston), the metonymical home of [NASA's Johnson Space Center](http://en.wikipedia.org/wiki/Lyndon_B._Johnson_Space_Center), as in _Houston, We Have Liftoff!_.\n\n## Installation\n\n    $ gem install houston\n\n## Usage\n\n```ruby\nrequire 'houston'\n\n# Environment variables are automatically read, or can be overridden by any specified options. You can also\n# conveniently use `Houston::Client.development` or `Houston::Client.production`.\nAPN = Houston::Client.development\nAPN.certificate = File.read('/path/to/apple_push_notification.pem')\n\n# An example of the token sent back when a device registers for notifications\ntoken = '\u003cce8be627 2e43e855 16033e24 b4c28922 0eeda487 9c477160 b2545e95 b68b5969\u003e'\n\n# Create a notification that alerts a message to the user, plays a sound, and sets the badge on the app\nnotification = Houston::Notification.new(device: token)\nnotification.alert = 'Hello, World!'\n\n# Notifications can also change the badge count, have a custom sound, have a category identifier, indicate available Newsstand content, or pass along arbitrary data.\nnotification.badge = 57\nnotification.sound = 'sosumi.aiff'\nnotification.category = 'INVITE_CATEGORY'\nnotification.content_available = true\nnotification.mutable_content = true\nnotification.custom_data = { foo: 'bar' }\nnotification.url_args = %w[boarding A998]\nnotification.thread_id = 'notify-team-ios'\n\n# And... sent! That's all it takes.\nAPN.push(notification)\n```\n\nTo generate a `.pem` file, it is recommended to use [fastlane pem](https://fastlane.tools/pem), which completely automates the process of creating the certificate.\n\n## Configuration\n\nHouston will attempt to load configuration data from environment variables, if they're present. The following variables will be used.\n\n| Environment Variable | Description |\n| --- | --- |\n| `APN_GATEWAY_URI` | The base URI for the APNS service to use. If left blank, will use the default APNS Production Gateway URI. |\n| `APN_FEEDBACK_URI` | The base URI for the APNS feedback service to use. If left blank, will use the default APNS Production Feedback URI. |\n| `APN_CERTIFICATE` | The file path to a valid APNS push certificate in `.pem` format (see \"[Converting Your Certificate](#converting-your-certificate)\" below). |\n| `APN_CERTIFICATE_DATA` | The contents of a valid APNS push certificate in `.pem` format (see \"[Converting Your Certificate](#converting-your-certificate)\" below); used in lieu of `APN_CERTIFICATE` if that variable is not provided. |\n| `APN_CERTIFICATE_PASSPHRASE` | If the APNS certificate is protected by a passphrase, provide this variable to use when decrypting it. |\n| `APN_TIMEOUT` | The timeout used when communicating with APNS. If not provided, the default of 0.5 seconds is used. |\n\n### Error Handling\n\nIf an error occurs when sending a particular notification, its `error` attribute will be populated:\n\n```ruby\nputs \"Error: #{notification.error}.\" if notification.error\n```\n\n### Silent Notifications\n\nTo send a silent push notification, set `sound` to an empty string (`''`):\n\n```ruby\nHouston::Notification.new(sound: '', content_available: true)\n```\n\n### Mutable Notifications\n\nTo send a mutable push notification (supported by iOS 10+), set `mutable_content` to `true`:\n\n```ruby\nHouston::Notification.new(mutable_content: true)\n```\n\n### Persistent Connections\n\nIf you want to manage your own persistent connection to Apple push services, such as for background workers, here's how to do it:\n\n```ruby\ncertificate = File.read('/path/to/apple_push_notification.pem')\npassphrase = '...'\nconnection = Houston::Connection.new(Houston::APPLE_DEVELOPMENT_GATEWAY_URI, certificate, passphrase)\nconnection.open\n\nnotification = Houston::Notification.new(device: token)\nnotification.alert = 'Hello, World!'\nconnection.write(notification.message)\n\nconnection.close\n```\n\n### Feedback Service\n\nApple provides a feedback service to query for unregistered device tokens, these are devices that have failed to receive a push notification and should be removed from your application. You should periodically query for and remove these devices, Apple audits providers to ensure they are removing unregistered devices. To obtain the list of unregistered device tokens:\n\n```ruby\nHouston::Client.development.devices\n```\n\nIn practice, you'll use a reference to instance of the APN object you create (see the Usage section). Here's a rake job that marks device tokens as invalid based on the feedback service from Apple. This example assumes devices are tracked in a model called Device (i.e. `User.devices`).\n\nIn `lib/tasks/notifications.rake`:\n\n```ruby\nnamespace :notifications do\n  task device_token_feedback: [:environment] do\n    APN.unregistered_devices.each do |device_hash|\n      # Format: { token: token, timestamp: timestamp }\n      device = Device.find_by(token: device_hash[:token])\n      next unless device.present?\n      # Remove device token\n      device.update_attribute(:device_token, nil)\n    end\n  end\nend\n```\n\n## Versioning\n\nHouston 2.0 supports the new [enhanced notification format](https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW4). Support for the legacy notification format is available in 1.x releases.\n\n## Command Line Tool\n\nHouston also comes with the `apn` binary, which provides a convenient way to test notifications from the command line.\n\n    $ apn push \"\u003ctoken\u003e\" -c /path/to/apple_push_notification.pem -m \"Hello from the command line! \"\n\n## Enabling Push Notifications on iOS\n\n### Objective-C\n\n```objective-c\n// AppDelegate.m\n\n- (void)applicationDidFinishLaunching:(UIApplication *)application {\n  // ...\n\n  [[UIApplication sharedApplication] registerForRemoteNotificationTypes:(UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound)];\n}\n\n- (void)application:(UIApplication *)application\ndidRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken\n{\n    NSLog(@\"application:didRegisterForRemoteNotificationsWithDeviceToken: %@\", deviceToken);\n\n    // Register the device token with a webservice\n}\n\n- (void)application:(UIApplication *)application\ndidFailToRegisterForRemoteNotificationsWithError:(NSError *)error\n{\n    NSLog(@\"Error: %@\", error);\n}\n```\n\n### Swift\n```swift\n// AppDelegate.swift\n\nfunc application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -\u003e Bool {\n    application.registerForRemoteNotifications()\n    return true\n}\n\nfunc application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {\n    // Register the device token with a webservice\n}\n\nfunc application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {\n    print(\"error \\(error)\")\n}\n```\n\n## Converting Your Certificate\n\n\u003e These instructions come from the [APN on Rails](https://github.com/PRX/apn_on_rails) project, which is another great option for sending push notifications.\n\nOnce you have the certificate from Apple for your application, export your key\nand the apple certificate as p12 files. Here is a quick walkthrough on how to do this:\n\n1. Click the disclosure arrow next to your certificate in Keychain Access and select the certificate and the key.\n2. Right click and choose `Export 2 items…`.\n3. Choose the p12 format from the drop down and name it `cert.p12`.\n\nNow convert the p12 file to a pem file:\n\n**Unencrypted private key (do not store this certificate in version control)**\n\n    $ openssl pkcs12 -in cert.p12 -out apple_push_notification.pem -nodes -clcerts\n\n**Encrypted private key**\n\n    $ openssl pkcs12 -in cert.p12 -out apple_push_notification.pem -aes256 -clcerts\n\nYou'll have to specify the password in the `APN_CERTIFICATE_PASSPHRASE` environment variable if you use the encrypted option.\n\n## License\n\nHouston is available under the MIT license. See the LICENSE file for more info.\n","funding_links":[],"categories":["Web 后端","Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnomad-cli%2Fhouston","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnomad-cli%2Fhouston","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnomad-cli%2Fhouston/lists"}