https://github.com/nullscreen/fb-core
A Ruby client for the Facebook Graph API
https://github.com/nullscreen/fb-core
gem
Last synced: 2 months ago
JSON representation
A Ruby client for the Facebook Graph API
- Host: GitHub
- URL: https://github.com/nullscreen/fb-core
- Owner: nullscreen
- License: mit
- Created: 2017-07-24T22:59:34.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2022-10-30T20:49:55.000Z (over 2 years ago)
- Last Synced: 2025-03-30T12:34:42.336Z (3 months ago)
- Topics: gem
- Language: Ruby
- Size: 73.2 KB
- Stars: 1
- Watchers: 8
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Fb::Core
Fb::Core provides methods to interact with Facebook users and pages through the Facebook Graph API.
[](https://travis-ci.org/Fullscreen/fb-core)
[](https://coveralls.io/r/Fullscreen/fb-core)
[](https://gemnasium.com/Fullscreen/fb-core)
[](https://codeclimate.com/github/Fullscreen/fb-core)
[](http://www.rubydoc.info/gems/fb-core/frames)
[](http://rubygems.org/gems/fb-core)
The **source code** is available on [GitHub](https://github.com/Fullscreen/fb-core) and the **documentation** on [RubyDoc](http://www.rubydoc.info/gems/fb-core/frames).
### Installing and Configuring
Add `fb-core` to your Gemfile and run `bundle install`.
Most methods of this library require to have an access token of a Facebook user.
If you need to obtain one programmatically, use the [fb-auth](https://github.com/Fullscreen/fb-auth) library.
## Usage
Fb::User#email
--------------
Given an user access token with the `email` scope, you can get the user's email by calling:
```ruby
user = Fb::User.new access_token: '--valid-access-token--'
user.email # => '[email protected]'
```
Fb::User#pages
--------------
Given an user access token with the `pages_show_list` scope, you can get the list of Facebook pages managed by the user by calling:
```ruby
user = Fb::User.new access_token: '--valid-access-token--'
user.pages
# => [#, #]
```
Fb::Page#posts
--------------
Given a page with posts, you can get the posts on the page since creation by calling:
```ruby
page = Fb::Page.new access_token: '--valid-access-token--', id: '--valid-id--'
page.posts
# => [#, #]
```
Pass `since` (`Time`) and `until` (`Time`) options to get posts in between the two times.
```ruby
options = { since: Time.new(2015, 05, 15), until: Time.now }
page.posts options
# => [#,..]
```
Pass `with_metrics: true` to include post insights for the following metrics...
All post types: `post_engaged_users`
Video posts only: `post_video_views_organic`, `post_video_views_paid`, `post_video_views`, and `post_video_view_time`
```ruby
page.posts with_metrics: true
# => [#,..]
```
You can also combine all three options...
```ruby
options = { since: Time.new(2015, 05, 15), until: Time.now, with_metrics: true }
page.posts options
```
Fb::Page#like_count
--------------
Given a page, you can get the the number of likes for the page.
```ruby
page = Fb::Page.new access_token: '--valid-access-token--', id: '--valid-id--'
page.like_count
# => 15000
```
Pass an `until` (`Date`) option to get the count at a certain date.
```ruby
page.like_count until: Date.today - 7
# => 10000
```
Fb::Page#view_count
--------------
You can also get the the number of views for the page.
```ruby
page = Fb::Page.new access_token: '--valid-access-token--', id: '--valid-id--'
page.view_count
# => 12345
```
Pass an `until` (`Date`) option to get the count at a certain date.
```ruby
page.view_count until: Date.today - 7
# => 10000
```
Fb::Page#weekly_insights
--------------
`weekly_insights` allows you to get metrics that are available weekly such as
`page_views_total`, `page_impressions`, `page_fan_adds`, etc. Refer to
[metrics](https://developers.facebook.com/docs/graph-api/reference/v2.9/insights#availmetrics)
for a list of available weekly metrics.
This method takes an array metrics and returns a hash of the metrics mapped to
their values. Each metric value is the sum of the last 7 days. If today is July 20th,
then the values will be for July 14 - July 20.
```ruby
metrics = %i(page_impressions page_fan_adds)
page = Fb::Page.new access_token: '--valid-access-token--', id: '--valid-id--'
page.weekly_insights metrics # sum for July 14 - 20
# => {:page_impressions => 1234, :page_fan_adds => 5678}
```
Pass an `until` (`Date`) option such as `Date.today - 7` to fetch 7 days prior to July 14th.
```ruby
page.weekly_insights metrics, until: Date.today - 7 # sum for July 8 - 14
# => {:page_impressions => 1234, :page_fan_adds => 5678}
```
Fb::Page#metric_insights
--------------
You can get an individual metric through using `metric_insights` which takes a
metric, period, and options (since & until). Refer to
[metrics](https://developers.facebook.com/docs/graph-api/reference/v2.9/insights#availmetrics)
for a list of available metrics and periods.
**Ensure that the period that you are using is supported by the metric**.
For example, `page_views_total` (page views) is available for `day`, `week`, and `days_28`
whereas `page_fans` (page likes) is only available as `lifetime`.
`metric_insights` returns a hash of Dates mapped to values. Passing `since` only return dates ahead
to this date (lower bound) and passing `until` will return dates previous to this day
(upper bound & defaults to 2 days ago). Combining both options will return the dates in between.
```ruby
page = Fb::Page.new access_token: '--valid-access-token--', id: '--valid-id--'
metric_insights = page.metric_insights 'page_views_total', :day # let today be August 7th
# => {# => 598, => 548}
```
With `until` (`Date`) and `since` (`Date`).
```ruby
options = {since: Date.today - 9, until: Date.today}
metric_insights = page.metric_insights metric, :day, options
# => {# => 639,..,# 548}
```
## Development
To run tests, obtain a long-term access token for a Facebook user who manages
at least one page and includes `email` and `manage_pages` scopes. Set the token as:
export FB_TEST_ACCESS_TOKEN="YourToken"
Then, run `rake spec` to run the tests.
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
Thanks :tada: