Brainzz
Brainzz explains why youtoobers' brainzz are turned to mush. ... by extracting data from the YouTube API.
Setup
$ bundle install
Run Specs
$ bundle exec rake
Regenerating VCR Cassettes
Check config/dotenv/test.env
for the required keys.
The values in this file are required environment variables
when consuming this gem.
Environment Variables
Single Content Owner
Brainzz requires the use of multiple environment variables:
BRAINZZ_GOOGLE_API_KEY
BRAINZZ_CLIENT_ID
BRAINZZ_CLIENT_SECRET
BRAINZZ_REFRESH_TOKEN
BRAINZZ_CONTENT_OWNER
:- the Google account for the CMS that owns the YouTube channel data.
Place values in config/dotenv/integration.env
.
Multiple Content Owners
The content owner must be passed in to the Brainzz method.
Use the environment variables above with the content owner added to it in upper case. Dashes also need to be remvoed.
For instance, if the content owner is abc-1234-DEF
,
you would use the following variables:
BRAINZZ_CLIENT_ID_ABC1234DEF
BRAINZZ_CLIENT_SECRET_ABC1234DEF
BRAINZZ_REFRESH_TOKEN_ABC1234DEF
Attaining BRAINZZ_GOOGLE_API_KEY
Follow the instructions here to find the required values.
Attaining BRAINZZ_REFRESH_TOKEN
An OAUTH refresh token for the BRAINZZ_CONTENT_OWNER
Google account
uses BRAINZZ_CLIENT_SECRET
and BRAINZZ_CLIENT_SECRET
BRAINZZ_CLIENT_ID
and BRAINZZ_CLIENT_SECRET
.
- Go to the Google OAuth Playground
- Log in with the Google account for
BRAINZZ_CONTENT_OWNER
- Click on the gear (upper-right)
- Click check box to "Use your own OAuth credentials"
- Fill in
BRAINZZ_CLIENT_ID
andBRAINZZ_CLIENT_SECRET
- In Step 1 (Select & Authorize APIs) scroll down to YouTube Analytics API v1
- Click the last item "yt-analytics.readonly"
- Click blue 'Authorize APIs' button
- Exchange code for tokens
- Grab value for the Refresh Token and store
Interface
All public endpoints are exposed in Brainzz::Core.
Every response from the public API is wrapped in a Response
object
that will always have the same interface regardless of request.
The Response#data
attribute will be an object specific to the data requested.
channel_details_for
Accepts an array of channel ids. The maximum length of the array is determined by YouTube.
This endpoint returns a hash with channel ids as keys and channel objects as the values.
Channel Attributes Accessible
id
title
published_at
description
uploads_playlist
likes_playlist
google_plus_id
view_count
comment_count
subscriber_count
video_count
Parameters
- channel ids (Array[String])
channel_list
Accepts a hash of options for the channels.list call. Allowing for you to get managed channels by content owner id.
This endpoint returns a hash with a list of channels.
Parameters
- options (Hash)
- content_owner_id (String)
playlist_items_for
On first invocation, only a playlist id is required:
playlist_id = 'my-playlist-id'
Brainzz.playlist_items_for playlist_id
This data is paginated, so if there are more than 50 results,
subsequent calls will need to pass in the response from the previous request.
In order to retrieve all playlist items,
the last_page?
attribute will need to be checked as well.
playlist_id = 'my-playlist-id'
response = nil
while response.nil? || !response.data.last_page?
response = Brainzz.playlist_items_for(playlist_id, response)
end
video_details_for
Accepts an array of video ids. The maximum length of the array is determined by YouTube. It is currently limited to 50 videos.
This endpoint returns a hash with video ids as keys and video objects as the values.
views_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
Result
An array of Brainzz::ViewCount
objects ordered by date in ascending order.
#source
will be an integer (or nil) value
corresponding to the following YouTube referrals:
ADVERTISING = 1
ANNOTATION = 2
EXT_URL = 3
NO_LINK_EMBEDDED = 4
NO_LINK_OTHER = 5
PLAYLIST = 6
PROMOTED = 7
RELATED_VIDEO = 8
SUBSCRIBER = 9
YT_CHANNEL = 10
YT_OTHER_PAGE = 11
YT_SEARCH = 12
The constants are defined in Brainzz::ViewCountEnum
.
view_totals_for
Parameters
Same as views_by_day_for
.
Result
Same as views_by_day_for
except date values are nil.
Views for date range are aggregated per source type.
likes_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::LikeCount
objects ordered by date in ascending order.
like_totals_for
Parameters
Same as likes_by_day_for
.
Result
Same as likes_by_day_for
except date values are nil.
Likes for date range are aggregated.
shares_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::ShareCount
objects ordered by date in ascending order.
share_totals_for
Parameters
Same as shares_by_day_for
.
Result
Same as shares_by_day_for
except date values are nil.
Shares for date range are aggregated.
dislikes_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::DislikeCount
objects ordered by date in ascending order.
dislike_totals_for
Parameters
Same as dislikes_by_day_for
.
Result
Same as dislikes_by_day_for
except date values are nil.
Dislikes for date range are aggregated.
comments_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::CommentCount
objects ordered by date in ascending order.
comment_totals_for
Parameters
Same as comments_by_day_for
.
Result
Same as comments_by_day_for
except date values are nil.
Comments for date range are aggregated.
subscribers_gained_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::SubscribersGainedCount
objects
ordered by date in ascending order.
subscribers_gained_totals_for
Parameters
Same as subscribers_gained_by_day_for
.
Result
Same as subscribers_gained_by_day_for
except date values are nil.
SubscribersGained for date range are aggregated.
subscribers_lost_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::SubscribersLostCount
objects
ordered by date in ascending order.
subscribers_lost_totals_for
Parameters
Same as subscribers_lost_by_day_for
.
Result
Same as subscribers_lost_by_day_for
except date values are nil.
SubscribersLost for date range are aggregated.
annotations_clickable_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::AnnotationsClickableCount
objects
ordered by date in ascending order.
annotations_clickable_totals_for
Parameters
Same as annotations_clickable_by_day_for
.
Result
Same as annotations_clickable_by_day_for
except date values are nil.
AnnotationsClickable for date range are aggregated.
annotations_clicked_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::AnnotationsClickedCount
objects
ordered by date in ascending order.
annotations_clicked_totals_for
Parameters
Same as annotations_clicked_by_day_for
.
Result
Same as annotations_clicked_by_day_for
except date values are nil.
AnnotationsClicked for date range are aggregated.
view_percentages_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::ViewPercentage
objects
ordered by date in ascending order.
view_percentage_totals_for
Parameters
Same as view_percentages_by_day_for
.
Result
Same as view_percentages_by_day_for
except date values are nil.
ViewPercentages for date range are aggregated.
view_durations_by_day_for
Parameters
- video ids (Array[String])
- start date (DateTime)
- end date (DateTime)
- content owner id (String)
Result
An array of Brainzz::ViewDuration
objects ordered by date in ascending order.
view_duration_totals_for
Parameters
Same as view_durations_by_day_for
.
Result
Same as view_durations_by_day_for
except date values are nil.
ViewDurations for date range are aggregated.
Factories
Brainzz includes FactoryGirl factories for your convenience. Include them after requiring FactoryGirl:
require 'brainzz/factories'
Deployment
This project makes use of branches to manage deployment.
Pushing a new commit to the production
branch
will also build and push this gem to RubyGems.