Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kit/instagram_basic_display

A client gem for the Instagram Basic Display API
https://github.com/kit/instagram_basic_display

Last synced: 8 months ago
JSON representation

A client gem for the Instagram Basic Display API

Awesome Lists containing this project

README 

          
# Instagram Basic Display



This is a client gem for Instagram’s [Basic Display API](https://developers.facebook.com/docs/instagram-basic-display-api/). It’s a small wrapper around the API that provides access to users’ media and profile information. Not every endpoint has been implemented, so pull requests are welcome to round things out!



Updates to the documentation are also very welcome!



## Installation



Add this line to your application's Gemfile:



```ruby

gem 'instagram_basic_display'

```



And then execute:



    $ bundle



Or install it yourself as:



    $ gem install instagram_basic_display



## Usage and examples



### Configuration



Set three environment variables to configure the client:



```

INSTAGRAM_CLIENT_ID=your_client_id

INSTAGRAM_CLIENT_SECRET=your_client_secret

INSTAGRAM_REDIRECT_URI=your_redirect_url

```



These variables can be obtained from the Facebook developer console.



### Using the client



When initializing the client, you can optionally pass in an auth token from Instagram, which will be used to make further requests. If you do not already have a token, you can use one of the methods provided to retrieve one.



```ruby

client = InstagramBasicDisplay::Client.new



# OR



client = InstagramBasicDisplay::Client.new(auth_token: token)

```



### Getting auth tokens



Authenticating with Instagram starts with an access code. This access code is retrieved by implementing Instagram's [authortization window](https://developers.facebook.com/docs/instagram-basic-display-api/overview#authorization-window), and is not covered by this gem.



Once you have an access code, you can exchange it for a short-lived authentication token.



```ruby

user = User.first

client = InstagramBasicDisplay::Client.new



short_token_request = client.short_lived_token(access_code: code)



if short_token_request.success?

  auth_token = token_request.payload.access_token

  expires_in = token_request.payload.expires_in

  user.update_instagram_token(token: token, expires_in: expires_in)

else

  render json: short_token_request.error, status: 400

end

```



You can exchange your short-lived token for a long-lived token.



```ruby

client = InstagramBasicDisplay::Client.new

user = User.first



long_token_request = client.long_lived_token(short_lived_token: user.instagram_token)



if long_token_request.success?

  auth_token = token_request.payload.access_token

  expires_in = token_request.payload.expires_in

  user.update_instagram_token(token: token, expires_in: expires_in)

else

  render json: long_token_request.error, status: 400

end

```



You can also pass an access code to `#long_lived_token`. It will be exchanged for a short-lived token, and then that will immediately be exchanged for a long-lived token.



```ruby

access_code = params[:access_code]

client = InstagramBasicDisplay::Client.new

user = User.first



long_token_request = client.long_lived_token(access_code: access_code)



if long_token_request.success?

  auth_token = token_request.payload.access_token

  expires_in = token_request.payload.expires_in

  user.update_instagram_token(token: token, expires_in: expires_in)

else

  render json: long_token_request.error, status: 400

end

```



You can refresh a long-lived token so that it remains valid for another period (at this stage, Instagram have set the validity period to 60 days).



```ruby

user = User.first

client = InstagramBasicDisplay::Client.new



refresh_request = client.refresh_long_lived_token(token: user.instagram_token)



if refresh_request.success?

  client.update_instagram_token(token: token_request.payload.access_token)

else

  render json: refresh_request.error, status: 400

end

```



To use an auth token when making requests, you can either pass it in when initializing the client,

or on-the-fly.



```ruby

auth_token = User.first.instagram_token



client = InstagramBasicDisplay::Client.new(auth_token: auth_token)



# OR



client = InstagramBasicDisplay::Client.new

client.configuration.auth_token = auth_token

```



### Getting profile information



You can retrieve a user's profile information (e.g. their username and Instagram id).



If no `user_id` is provided, the request will be made against the user associated with the client's auth token. For example:



```ruby

auth_token = User.first.instagram_token



client = InstagramBasicDisplay::Client.new(auth_token: auth_token)

response = client.profile



instagram_id = response.payload.id

instagram_username = response.payload.username

```



But you can also pass in a `user_id`, and request specific profile fields. Check the Instagram documentation to find out [which fields are supported](https://developers.facebook.com/docs/instagram-basic-display-api/reference/user#fields).



```ruby

user = User.first



client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)

response = client.profile(user_id: user.instagram_id, fields: %i[username])



instagram_username = response.payload.username

```



### Getting media



You can query a user's media feed like this:



```ruby

user = User.first



client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)

response = client.media_feed



media = response.payload.data

```



You can query for specific fields on the media, but by default you'll receive the `id` and `media_url` of each item. Refer to the Instagram documentation to [find out about other fields](https://developers.facebook.com/docs/instagram-basic-display-api/reference/media/).



```ruby

user = User.first



client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)

response = client.media_feed(fields: %i[caption media_url])



media = response.payload.data

```



For pagination, the Instagram API provides previous/next links. Use those to retrieve the next page of results.



```ruby



user = User.first



client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)



first_page = client.media_feed(fields: %i[caption media_url])



# you can ask the response whether there is a next/previous page

has_next_page_link = first_page.next_page?



# or ask for the url

next_page_link = first_page.next_page_link



second_page = client.media_feed(fields: %i[caption media_url], paginated_url: next_page_link)

```



You can pass some additional parameters to the media feed. They aren't yet well-documented by Instagram, but you can make some reasonable guesses at what will be accepted, based on the Facebook API. For example, to limit the number of results retrieved:



```ruby

user = User.first



client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)

client.media_feed(limit: 10)

```



To retrieve a single piece of media, you'll need to know its id. As with the other requests, you can request whichever fields are supported by Instagram.



```ruby

user = User.first

client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)



client.media_node(media_id: id, fields: %i[caption media_url id])

```



## 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](https://rubygems.org).



## Contributing



Bug reports and pull requests are welcome on GitHub at https://github.com/convertkit/instagram_basic_display. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.