An oEmbed consumer library written in Ruby, letting you easily get embeddable HTML representations of supported web pages, based on their URLs. See oembed.com for more about the protocol.
gem install ruby-oembed
The easiest way to use this library is to make use of the built-in providers.
OEmbed::Providers.register_allresource=OEmbed::Providers.get('http://www.youtube.com/watch?v=2BYXBC8WQ5k')resource.video?#=> trueresource.thumbnail_url#=> "http://i3.ytimg.com/vi/2BYXBC8WQ5k/hqdefault.jpg"resource.html#=> <<-HTML
<objectwidth="425"height="344">
<paramname="movie"value="http://www.youtube.com/v/2BYXBC8WQ5k?fs=1"></param> <param name="allowFullScreen" value="true"></param>
<paramname="allowscriptaccess"value="always"></param> <embed src="http://www.youtube.com/v/2BYXBC8WQ5k?fs=1" type="application/x-shockwave-flash" width="425" height="344" allowscriptaccess="always" allowfullscreen="true"></embed> </object>
HTMLSome built-in providers require authorization in order to work. These providers won't be registered unless an access token is provided. You can either pass access tokens to the register_app method.
OEmbed::Providers.register_all(access_tokens: {facebook: @my_facebook_token})Or you can provide access tokens via environment variable
ENV['OEMBED_FACEBOOK_TOKEN']#=> 'my-access-token'OEmbed::Providers.register_all| access_token | environment variable | Associated Providers |
|---|---|---|
:facebook | OEMBED_FACEBOOK_TOKEN | FacebookPost, FacebookVideo, Instagram |
If you'd like to use a provider that isn't included in the library, it's easy to create one. Just provide the oEmbed API endpoint and URL scheme(s).
my_provider=OEmbed::Provider.new("http://my.cool-service.com/api/oembed_endpoint.{format}")my_provider << "http://*.cool-service.com/image/*"my_provider << "http://*.cool-service.com/video/*"You can then use your new custom provider or you can register it along with the rest of the built-in providers.
resource=my_provider.get("http://a.cool-service.com/video/1")#=> OEmbed::Responseresource.provider.name#=> "My Cool Service"OEmbed::Providers.register(my_provider)resource=OEmbed::Providers.get("http://a.cool-service.com/video/2")#=> OEmbed::ResponseLast but not least, ruby-oembed supports Noembed, Embedly, provider discovery. The first two are provider aggregators. Each supports a wide array of websites ranging from Amazon.com to xkcd. The later is part of the oEmbed specification that allows websites to advertise support for the oEmbed protocol.
OEmbed::Providers.register_fallback(OEmbed::ProviderDiscovery,OEmbed::Providers::Noembed)OEmbed::Providers.get('https://www.xkcd.com/802/')#=> OEmbed::ResponseThis library works wonderfully on its own, but can get a speed boost by using 3rd party libraries to parse oEmbed data. To use a 3rd party Formatter, just be sure to require the library before ruby-oembed (or include them in your Gemfile before ruby-oembed).
require'json'require'xmlsimple'require'oembed'OEmbed::Formatter::JSON.backend#=> OEmbed::Formatter::JSON::Backends::JSONGemOEmbed::Formatter::XML.backend#=> OEmbed::Formatter::XML::Backends::XmlSimpleThe following, optional, backends are currently supported:
- The JSON implementation for Ruby
- Rails' ActiveSupport::JSON (confirmed to work with Rails 3.0.x and should work with Rails 2.0+)
- XmlSimple
Code for the ruby-oembed library is hosted on GitHub.
# Get the code.
git clone git://github.com/ruby-oembed/ruby-oembed.git
cd ruby-oembed
# Install all development-related gems.
gem install bundler
bundle install
# Run the tests.
bundle exec rake
# or run the test continually
bundle exec guardIf you encounter any bug, feel free to create an Issue.
We gladly accept pull requests! Just fork the library and commit your changes along with relevant tests. Once you're happy with the changes, send a pull request.
We do our best to keep our tests green
Thanks to all who have made contributions to this gem, both large and small.
This code is free to use under the terms of the MIT license.