joelvh/apps

Easily integrate with multiple platform apps/add-ins/add-ons marketplaces.

Apps

This is a toolkit to easily integrate into platform marketplaces and extension points. These tools help with various integration points and common boilerplate needed to get going.

The Apps gem is currently under development, with the goal of facilitating the following:

• Gmail
  • Add-ons
  • Email Markup
  • AMP Pages
• Microsoft Office 365
  • Outlook Add-ins
  • Outlook Actionable Messages
• Slack
  • Bot Users
  • Slash Commands
• Heroku Elements Marketplace
  • Add-ons
• Facebook
  • Instant Articles
• Google
  • Progressive Web Apps

Installation

Add this line to your application's Gemfile:

gem 'apps'

And then execute:

$ bundle

Or install it yourself as:

$ gem install apps

Usage

Gmail Email Markup

You can generate schema.org markup for email in Gmail utilizing simple helper classes. Use the helper methods in Apps::Gmail::Markup to easily define your markup.

• Confirm Action
• Save Action
• RSVP Action
• View Action
• Track Action

Explore Apps::Gmail::Markup and related classes to see how you can customize your metadata.

require 'apps/gmail/markup'

# Confirm Action (takes additional keyword options)
confirm_action = Apps::Gmail::Markup.confirm_action('Button Text', 'http://example.org/confirm/endpoint')

confirm_action.as_json
# => {"@context"=>"http://schema.org", "@type"=>"EmailMessage", "potentialAction"=>{"@type"=>"ConfirmAction", "handler"=>{"@type"=>"HttpActionHandler", "url"=>"http://example.org/confirm/endpoint"}}}

puts confirm_action.to_json
# => {"@context":"http://schema.org","@type":"EmailMessage","potentialAction":{"@type":"ConfirmAction","handler":{"@type":"HttpActionHandler","url":"http://example.org/confirm/endpoint"}}}

# NOTE: `to_script` is only available on "context" objects that represent the root of the markup
#       needed for embedding in emails. This is the object returned by each of the helper methods
#       above for each "Action"
puts confirm_action.to_script
# =>
# <script type="application/ld+json">
# {
#   "@context": "http://schema.org",
#   "@type": "EmailMessage",
#   "potentialAction": {
#     "@type": "ConfirmAction",
#     "handler": {
#       "@type": "HttpActionHandler",
#       "url": "http://example.org/confirm/endpoint"
#     }
#   }
# }
# </script>

# Save Action (takes additional keyword options)
save_action = Apps::Gmail::Markup.save_action('Button Text', 'http://example.org/save/endpoint')

# RSVP Action (takes additional keyword options)
rsvp_action = Apps::Gmail::Markup.rsvp_action('Event Name',
                yes_url:   'http://example.org/yes/endpoint',
                no_url:    'http://example.org/no/endpoint',
                maybe_url: 'http://example.org/maybe/endpoint'
              )

# View Action (takes additional keyword options)
view_action = Apps::Gmail::Markup.view_action('Button Text', 'http://example.org/save/endpoint')

# Track Action (takes additional keyword options)
track_action = Apps::Gmail::Markup.track_action('Button Text', 'http://example.org/save/endpoint')

You need to register with Google to get your actions approved.

Related Resoures:

• Embeding JSON-LD in HTML Documents
• Test Your Schemas
  • Email Markup Tester
  • Structured Data Markup Helper
• Register with Google
• Articles:
  • A Guide to Setting up Gmail Inbox Actions by Meldium

TODO

• Basic handler endpoints for "Actions" to interact with need to be facilitated (e.g. for RSVP Action)
• Email Markup helpers for other Gmail-supported metadata need to be implemented
• Additional Gmail integrations need to be developed

Microsoft Office 365

• Office Developer - git repositories of example projects for Outlook Add-ins, etc.
• Yeoman generator - generator for creating Microsoft office Add-ins
• Message Card Playground - test schema.org markup and how it generates add-in UI

Outlook: Actionable Messages via Email

All Actionable Card markup schemas supported by Microsoft Office are implemented in this library (see Actionable message card reference).

require 'apps/outlook/actionable_messages'

message_card = Apps::Outlook::ActionableMessages.message_card('Summary text', 'Title text')

You can take a look at (and run) lib/examples.rb to see some sample markup.

$ ruby lib/examples.rb

You can get more example schemas or copy/paste the output of examples.rb to test rendering here: https://messagecardplayground.azurewebsites.net/

Related Resources:

• Actionable Messages via Email
  • Actionable message card reference
• Register your service with the actionable email developer dashboard
• Register your connector with the Office 365 Connectors developer dashboard - setup a connector for users to authorize your add-in

Development

After 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.

To 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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/joelvh/apps. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.