flayyer 1.2.0 → 1.3.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (7) hide show
  1. checksums.yaml +4 -4
  2. data/Gemfile +1 -0
  3. data/Gemfile.lock +3 -1
  4. data/README.md +128 -22
  5. data/lib/flayyer.rb +87 -4
  6. data/lib/flayyer/version.rb +1 -1
  7. metadata +6 -6
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 9f3cd5589505248711256b44531dfe472c9fb2678e58bc74f8737de32d8bc0b7
4
- data.tar.gz: 96d4cfbdf0fe2ebfcfea5bed7e5ebc6f7a4f66aaf1ded19620bea0df0a273b04
3
+ metadata.gz: ab8b57ccf6cf696650db8f8223a83240a069f223431de064be5363da1a0a91c7
4
+ data.tar.gz: fb90fe7e11bb0d7d053cd9a8f3fd2418e2eef70659516b7eb96f5e25b91ee8d4
5
5
  SHA512:
6
- metadata.gz: e5152bc7884de73a23808fea60f29daa2aa2f25d639b3ceb0d46ac6857d3d0522dbcb9e195a58159d15fcf98860490a34c577f94041f6e0745e55d3a3b943461
7
- data.tar.gz: 47f36829fe4ead59e35d1581b42e9444768dd834463a06e37fb9dc754303e501e73c3003b9f21a70e0975792f8ab5146b597ec0833374728c0e058c116427dc9
6
+ metadata.gz: a7e29b903b89c51048bce1e129f8b550591f7685cace6444241ca566f3ab57ace155597fbd13e571f57c2b3038c6e34f4fcd1a5cc6c980fff9ecef68d7ded1e1
7
+ data.tar.gz: da94f03fa7b9fe8bb5a9744ceb9bd6cdbf71a67e2510315274163fd85d61bdc03b4695d4f0fad4a8d6afeff2ec2a2bc9ac3061bc96570751e85da9b646838eb2
data/Gemfile CHANGED
@@ -7,3 +7,4 @@ gem 'rake', '~> 12.0'
7
7
  group :test do
8
8
  gem 'rspec', '~> 3.0'
9
9
  end
10
+ gem 'jwt'
data/Gemfile.lock CHANGED
@@ -1,12 +1,13 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- flayyer (1.2.0)
4
+ flayyer (1.3.0)
5
5
 
6
6
  GEM
7
7
  remote: https://rubygems.org/
8
8
  specs:
9
9
  diff-lcs (1.4.4)
10
+ jwt (2.2.2)
10
11
  rake (12.3.3)
11
12
  rspec (3.10.0)
12
13
  rspec-core (~> 3.10.0)
@@ -27,6 +28,7 @@ PLATFORMS
27
28
 
28
29
  DEPENDENCIES
29
30
  flayyer!
31
+ jwt
30
32
  rake (~> 12.0)
31
33
  rspec (~> 3.0)
32
34
 
data/README.md CHANGED
@@ -1,10 +1,24 @@
1
1
  # flayyer-ruby
2
2
 
3
- This gem is agnostic to any Ruby framework and has zero external dependencies.
3
+ The AI-powered preview system built from your website (no effort required).
4
4
 
5
- To create a FLAYYER template please refer to: [flayyer.com](https://flayyer.com?ref=flayyer-ruby)
5
+ ![Flayyer live image](https://github.com/flayyer/create-flayyer-app/blob/master/.github/assets/website-to-preview.png?raw=true&v=1)
6
6
 
7
- ## Installation
7
+ **This gem is agnostic to any Ruby framework.**
8
+
9
+ ## Index
10
+
11
+ - [Get started (5 minutes)](#get-started-5-minutes)
12
+ - [Advanced usage](#advanced-usage)
13
+ - [Flayyer.io](#flayyerio)
14
+ - [Development](#development)
15
+ - [Test](#test)
16
+
17
+ ## Get started (5 minutes)
18
+
19
+ Haven't registered your website yet? Go to [Flayyer.com](https://flayyer.com?ref=flayyer-ruby) and create a project (e.g. `website-com`).
20
+
21
+ ### 1. Install the library
8
22
 
9
23
  Add this line to your application's Gemfile:
10
24
 
@@ -24,9 +38,110 @@ Or install it yourself as:
24
38
  gem install flayyer
25
39
  ```
26
40
 
27
- ## Usage
41
+ ### 2. Get your Flayyer.ai smart image link
42
+
43
+ In your website code (e.g. your landing or product/post view file), set the following:
44
+
45
+ ```ruby
46
+ flayyer = Flayyer::FlayyerAI.create do |f|
47
+ # Your project slug
48
+ f.project = 'website-com'
49
+ # The current path of your website
50
+ f.path = '/path/to/product' # In Ruby on Rails you can use `request.env['PATH_INFO']`
51
+ end
52
+
53
+ # Check:
54
+ puts flayyer.href
55
+ # > https://flayyer.ai/v2/website-com/_/__v=1618281823/path/to/product
56
+ ```
57
+
58
+ ### 3. Put your smart image link in your `<head>` tags
59
+
60
+ You'll get the best results like this:
61
+
62
+ ```ruby
63
+ # .haml
64
+ %meta{ property: 'og:image', content: flayyer.href }
65
+ %meta{ name: 'twitter:image', content: flayyer.href }
66
+ %meta{ name: 'twitter:card', content: 'summary_large_image' }
67
+
68
+ # .erb
69
+ <meta property="og:image" content='<%= flayyer.href %>'>
70
+ <meta name="twitter:image" content='<%= flayyer.href %>'>
71
+ <meta name="twitter:card" content="summary_large_image">
72
+
73
+ # IMPORTANT: if you're using Ruby on Rails, please use `flayyer.href.html_safe` to prevent double serialization
74
+ ```
75
+
76
+ ### 4. Create a `rule` for your project
77
+
78
+ Login at [Flayyer.com](https://flayyer.com?ref=flayyer-ruby) > Go to your Dashboard > Manage rules and create a rule like the following:
79
+
80
+ [![Flayyer basic rule example](https://github.com/flayyer/create-flayyer-app/blob/master/.github/assets/rule-example.png?raw=true&v=1)](https://flayyer.com/dashboard)
81
+
82
+ Voilà!
83
+
84
+ ## Advanced usage
85
+
86
+ Advanced features include:
87
+
88
+ - Custom variables: additional information for your preview that is not present in your website. [Note: if you need customization you should take a look at [Flayyer.io](#flayyerio)]
89
+ - Custom metadata: set custom width, height, resolution, and more (see example).
90
+ - Signed URLs.
91
+
92
+ Here you have a detailed full example for project `website-com` and path `/path/to/product`.
93
+
94
+ ```ruby
95
+ flayyer = Flayyer::FlayyerAI.create do |f|
96
+ # [Required] Your project slug, find it in your dashboard https://flayyer.com/dashboard/.
97
+ f.project = 'website-com'
98
+ # [Recommended] The current path of your website (by default it's `/`).
99
+ f.path = '/path/to/product'
100
+ # [Optional] In case you want to provide information that is not present in your page set it here.
101
+ f.variables = {
102
+ 'title': 'Product name',
103
+ 'img': 'https://flayyer.com/img/marketplace/flayyer-banner.png',
104
+ }
105
+ # [Optional] Custom metadata for rendering the image. ID is recommended so we provide you with better statistics.
106
+ f.meta = {
107
+ 'id': 'jeans-123', # recommended for better stats
108
+ 'v': '12369420123', # specific handler version, by default it's a random number to circumvent platforms' cache,
109
+ 'width': 1200,
110
+ 'height': 600,
111
+ 'resolution': 0.9, # from 0.0 to 1.0
112
+ 'agent': 'whatsapp', # force dimensions for specific platform
113
+ }
114
+ end
115
+
116
+ # Use this image in your <head/> tags (og:image & twitter:image)
117
+ puts flayyer.href
118
+ # > https://flayyer.ai/v2/website-com/_/__id=jeans-123&__v=1618281823&img=https%3A%2F%2Fflayyer.com%2Fimg%2Fmarketplace%2Fflayyer-banner.png&title=Product+name/path/to/product
119
+
120
+ # IMPORTANT: if you're using Ruby on Rails, please use `flayyer.href.html_safe` to prevent double serialization
121
+ ```
122
+
123
+ For signed URLs, just provide your secret (find it in Dashboard > Project > Advanced settings) and choose a strategy (`HMAC` or `JWT`).
124
+
125
+ ```ruby
126
+ flayyer = Flayyer::FlayyerAI.create do |f|
127
+ f.project = 'website-com'
128
+ f.path = '/path/to/product'
129
+ f.secret = 'your-secret-key'
130
+ f.strategy = 'JWT' # or 'HMAC'
131
+ end
132
+
133
+ url = flayyer.href
134
+ # > https://flayyer.ai/v2/website-com/jwt-eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwYXJhbXMiOnsiX19pZCI6ImplYW5zLTEyMyJ9LCJwYXRoIjoiXC9wYXRoXC90b1wvcHJvZHVjdCJ9.X8Vs5SGEA1-3M6bH-h24jhQnbwH95V_G0f-gPhTBTzE?__v=1618283086
135
+
136
+ # IMPORTANT: if you're using Ruby on Rails, please prevent double serialization like the following:
137
+ url = flayyer.href.html_safe
138
+ ```
139
+
140
+ ## Flayyer.io
141
+
142
+ As you probably realized, Flayyer.ai uses the [rules defined on your dashboard](https://flayyer.com/dashboard/_/projects) to decide how to handle every image based on path patterns. It fetches and analyse your website for obtaining information and then rendering a content-rich image increasing the click-through-rate with no effort. Let's say _"FlayyerAI render images based on the content of this route"_.
28
143
 
29
- After installing the gem you can format URL as:
144
+ Flayyer.io instead requires you to explicitly declare template and variables for the images to render, **giving you more control for customization**. Let's say _"FlayyerIO render an image using this template and these explicit variables"_.
30
145
 
31
146
  ```ruby
32
147
  require 'flayyer'
@@ -43,6 +158,9 @@ end
43
158
  # Use this image in your <head/> tags
44
159
  url = flayyer.href
45
160
  # > https://flayyer.io/v2/tenant/deck/template.jpeg?__v=1596906866&title=Hello+world%21
161
+
162
+ # IMPORTANT: if you're using Ruby on Rails, please prevent double serialization like the following:
163
+ url = flayyer.href.html_safe
46
164
  ```
47
165
 
48
166
  Variables can be complex arrays and hashes.
@@ -71,28 +189,16 @@ print(CGI.unescape(url))
71
189
  # > https://flayyer.io/v2/tenant/deck/template.jpeg?title=Hello+world!&__v=123
72
190
  ```
73
191
 
74
- ## Ruby on Rails
75
-
76
- Ruby on Rails will try to safely render strings into the HTML. Any FLAYYER string is already safe-serialized and should not be serialized again.
77
-
78
- To prevent double serialization make sure to call `.html_safe` like this:
79
-
80
- ```ruby
81
- url = flayyer.href.html_safe
82
- ```
83
-
84
- > https://apidock.com/rails/String/html_safe
85
-
86
192
  ## Development
87
193
 
88
194
  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.
89
195
 
90
196
  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](https://rubygems.org).
91
197
 
92
- ## Contributing
198
+ ## Test
93
199
 
94
- Bug reports and pull requests are welcome on GitHub at https://github.com/flayyer/flayyer-ruby.
200
+ Run Rake tests with:
95
201
 
96
- ## License
97
-
98
- The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
202
+ ```sh
203
+ rake spec
204
+ ```
data/lib/flayyer.rb CHANGED
@@ -1,9 +1,92 @@
1
1
  require 'flayyer/version'
2
2
  require 'uri'
3
+ require 'openssl'
4
+ require 'jwt'
3
5
 
4
6
  module Flayyer
5
7
  class Error < StandardError; end
6
8
 
9
+ class FlayyerAI
10
+ attr_accessor :project, :path, :variables, :meta, :secret, :strategy
11
+
12
+ def self.create(&block)
13
+ self.new(&block)
14
+ end
15
+
16
+ def initialize(project = nil, path = nil, variables = {}, meta = {}, secret = nil, strategy = nil)
17
+ @project = project
18
+ @path = path || "/"
19
+ @variables = variables
20
+ @meta = meta
21
+ @secret = secret
22
+ @strategy = strategy
23
+ yield(self) if block_given?
24
+ end
25
+
26
+ def path_safe
27
+ @path.start_with?("/") ? @path : "/#{@path}"
28
+ end
29
+
30
+ def params_hash(ignoreV)
31
+ defaults = {
32
+ __v: @meta[:v] || Time.now.to_i, # This forces crawlers to refresh the image
33
+ __id: @meta[:id] || nil,
34
+ _w: @meta[:width] || nil,
35
+ _h: @meta[:height] || nil,
36
+ _res: @meta[:resolution] || nil,
37
+ _ua: @meta[:agent] || nil
38
+ }
39
+ defaults.delete(:__v) if ignoreV
40
+ @variables.nil? ? defaults : defaults.merge(@variables)
41
+ end
42
+
43
+ def querystring(ignoreV = false)
44
+ # Allow accesing the keys of @meta with symbols and strings
45
+ # https://stackoverflow.com/a/10786575
46
+ @meta.default_proc = proc do |h, k|
47
+ case k
48
+ when String then sym = k.to_sym; h[sym] if h.key?(sym)
49
+ when Symbol then str = k.to_s; h[str] if h.key?(str)
50
+ end
51
+ end
52
+
53
+ defaults = self.params_hash(ignoreV)
54
+ result = FlayyerHash.new(defaults)
55
+ result.to_query.split("&").sort().join("&")
56
+ end
57
+
58
+ def sign
59
+ return '_' if @strategy.nil? and @secret.nil?
60
+ raise Error.new('Got `strategy` but missing `secret`. You can find it in your project in Advanced settings.') if @secret.nil?
61
+ raise Error.new('Got `secret` but missing `strategy`. Valid options are `HMAC` or `JWT`.') if @strategy.nil?
62
+ key = @secret
63
+ data = "#{@project}#{self.path_safe}#{self.querystring(true)}"
64
+ if strategy.downcase == "hmac" then
65
+ mac = OpenSSL::HMAC.hexdigest('SHA256', key, data)
66
+ mac[0..15]
67
+ elsif strategy.downcase == "jwt"
68
+ payload = { "params": self.params_hash(true).compact, "path": self.path_safe}
69
+ JWT.encode(payload, key, 'HS256')
70
+ else
71
+ raise Error.new('Invalid `strategy`. Valid options are `HMAC` or `JWT`.')
72
+ end
73
+ end
74
+
75
+ # Create a https://FLAYYER.com string.
76
+ # If you are on Ruby on Rails please use .html_safe when rendering this string into the HTML
77
+ def href
78
+ raise Error.new('Missing "project" property') if @project.nil?
79
+
80
+ signature = self.sign
81
+ params = self.querystring
82
+ if strategy.nil? || strategy != "JWT" then
83
+ "https://flayyer.ai/v2/#{@project}/#{signature}/#{params}#{self.path_safe}"
84
+ else
85
+ "https://flayyer.ai/v2/#{@project}/jwt-#{signature}?__v=#{@meta[:v] || Time.now.to_i}"
86
+ end
87
+ end
88
+ end
89
+
7
90
  class FlayyerURL
8
91
  attr_accessor :version, :tenant, :deck, :template, :extension, :variables, :meta
9
92
 
@@ -30,21 +113,21 @@ module Flayyer
30
113
  when String then sym = k.to_sym; h[sym] if h.key?(sym)
31
114
  when Symbol then str = k.to_s; h[str] if h.key?(str)
32
115
  end
33
- end
116
+ end
34
117
 
35
118
  defaults = {
36
- __v: @meta[:v] || Time.now.to_i, # This forces crawlers to refresh the image
119
+ __v: @meta[:v].nil? ? Time.now.to_i : @meta[:v], # This forces crawlers to refresh the image
37
120
  __id: @meta[:id] || nil,
38
121
  _w: @meta[:width] || nil,
39
122
  _h: @meta[:height] || nil,
40
123
  _res: @meta[:resolution] || nil,
41
- _ua: @meta[:agent] || nil,
124
+ _ua: @meta[:agent] || nil
42
125
  }
43
126
  result = FlayyerHash.new(@variables.nil? ? defaults : defaults.merge(@variables))
44
127
  result.to_query
45
128
  end
46
129
 
47
- # Create a https://FLAYYER.com string.
130
+ # Create a https://flayyer.com string.
48
131
  # If you are on Ruby on Rails please use .html_safe when rendering this string into the HTML
49
132
  def href
50
133
  raise Error.new('Missing "tenant" property') if @tenant.nil?
data/lib/flayyer/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  module Flayyer
2
- VERSION = '1.2.0'
2
+ VERSION = '1.3.0'
3
3
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: flayyer
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.2.0
4
+ version: 1.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Patricio López Juri
8
- autorequire:
8
+ autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2020-12-19 00:00:00.000000000 Z
11
+ date: 2021-05-29 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: FLAYYER.com helper classes and methods
14
14
  email:
@@ -38,7 +38,7 @@ metadata:
38
38
  homepage_uri: https://github.com/flayyer/flayyer-ruby
39
39
  source_code_uri: https://github.com/flayyer/flayyer-ruby
40
40
  changelog_uri: https://github.com/flayyer/flayyer-ruby
41
- post_install_message:
41
+ post_install_message:
42
42
  rdoc_options: []
43
43
  require_paths:
44
44
  - lib
@@ -53,8 +53,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
53
53
  - !ruby/object:Gem::Version
54
54
  version: '0'
55
55
  requirements: []
56
- rubygems_version: 3.1.2
57
- signing_key:
56
+ rubygems_version: 3.0.6
57
+ signing_key:
58
58
  specification_version: 4
59
59
  summary: FLAYYER.com helper classes and methods
60
60
  test_files: []