mweibel / facebook.ex

Facebook Graph API Wrapper written in Elixir

facebook.ex

Facebook Graph API Wrapper written in Elixir. (documentation)

Installation

Add facebook.ex as a dependency in your mix.exs file.

defp deps do
  [{:facebook, "~> 0.24.0"}]
end

After you are done, run this in your shell to fetch the new dependency:

$ mix deps.get

Configuration

You can configure facebook.ex in your mix config.exs (or, if you're using the Phoenix Framework, in your config/dev.exs|test.exs|prod.exs, respectively) with the following keys, which state the library defaults:

config :facebook,
  app_id: nil,
  app_secret: nil,
  app_access_token: nil,
  graph_url: "https://graph.facebook.com",
  graph_video_url: "https://graph-video.facebook.com",
  request_conn_timeout: nil,
  request_recv_timeout: nil

For graph_url and video_graph_url, Facebook automatically uses the oldest active Graph API version available if you don't specify a version in the url. You may use versioned urls to pin your calls to a specific API versions (recommended), e.g. like so:

  graph_url: "https://graph.facebook.com/v2.11",
  graph_video_url: "https://graph-video.facebook.com/v2.8"

Note that you must not end the urls with a slash or the requests will fail (Facebook will report an error about unknown url components)!

app_id, app_secret and app_access_token do not need to be supplied if you are using no Graph API calls that require them (e.g. payment calls).

If you supply the app_secret, an appsecret_proof will be submitted along with the Graph API requests. The app_secret can be changed (or set) at runtime using Facebook.set_app_secret("<app secret>").

You can also configure facebook.ex library in runtime using {:system, _} tuples:

config :facebook,
  app_id: {:system, "APP_ID"},
  app_secret: {:system, "APP_SECRET"},
  app_access_token: {:system, "APP_ACCESS_TOKEN"},
  graph_url: {:system, "GRAPH_URL"},
  graph_video_url: {:system, "GRAPH_VIDEO_URL"},
  request_conn_timeout: {:system, :integer, "REQUEST_CONN_TIMEOUT"},
  request_recv_timeout: {:system, :integer, "REQUEST_RECV_TIMEOUT"}

Note that if you use {:system, _} (or {:system, :integer, _}) tuple but don't provide the corresponding environment variable application will crash on startup to prevent unexpected behaviour later.

Usage

1. Register an application on developer.facebook.com
2. Get an access_token from Facebook's Access Token Tool

Then you can get started with code.

Start an iex shell in your project folder:

$ iex -S mix

Then try some API calls:

iex(1)> Facebook.me("first_name", "ACCESSTOKEN")
{:ok, %{"first_name" => "Michael"}} # <--- that's the return value

iex(2)> Facebook.object_count(:likes, "262588213843476_801732539929038", "ACCESSTOKEN")
{:ok, 48} # <--- that's the return value

Contributing

We encourage contribution from anyone! If you've got an improvement to the documentation or feature you've implemented, please open a pull request. This project uses credo for code analysis. Running mix credo will give you a nice output which will tell you if any of the changes you've made aren't consistent with the rest of our codebase.

The Facebook Graph API is fairly large and as such we're not using every facet of it, so if you're not seeing an edge that is handled, please report an issue or open a pull request to add it.

facebook.ex's Issues

Batch support

I would like to add support for batch requests. I think this will necessitate some design changes. In particular, I think it means many of the API methods should return a request instead of a response, and then adding a new function that sends one or a batch of requests together and returns a response.

Here's how it might(?) look:

pages = Repo.all(Page)
  |> Enum.map(fn page -> Facebook.page(page.facebook_page_id) end)
  |> Facebook.requestBatch()

Method names should be in snake case

By convention, method names should be in snake_case, see https://github.com/elixir-lang/elixir/blob/master/lib/elixir/pages/Naming%20Conventions.md#casing

Elixir developers must use snake_case when defining variables, function names, module attributes, etc

It's super weird to use your library when it's the only one using camel case.

Versioned graph url doesn't work with exchanging long lived access token

I want to pin the API version my app will be using. To do so, I set the graph_url with Facebook's versioning scheme to a specific version, like this one: https://graph.facebook.com/v2.11/.
This, however, breaks the long_lived_access_token call as the uri used therein (/oauth/access_token) isn't available in versioned paths, only at root.
Maybe the config could introduce a parameter graph_api_version which will be appended only to the calls which are available under versioned urls. What do you think?

module :hmac is not available

Error, when using Facebook.me()

** (UndefinedFunctionError) undefined function :hmac.hexlify/2 (module :hmac is not available)

To get around this I needed to specify the github repo in mix.exs

Inconsistent Returns

Noticed that some methods return a tuple, like:

{:json, %{"email" => email}} = Facebook.me([fields: "email"], access_token)

Whereas other methods return a map, like:

%{"access_token" => access_token} = Facebook.accessToken

Is this done for a particular reason? If not, would you be open to a PR that makes the returns consistent?

Facebook Page info

I am writing a little experimental service in Elixir and need to access info about a user's facebook pages. Would you accept a PR for adding a basic wrapper for the /page node?

It looks like I could pretty easily follow the current code for /me, any concerns or other design we should do?

Ability to upload images/videos

Is it currently possible to upload videos/images with this package?

New version

Could you release the new version to hex.pm?

Ability to add custom params and few other features

Thank you for all the effort, a really useful library to have in elixir.
One issue faced was providing custom parameters like "since" etc and also, not having a clean abstraction for things like getting the next page in a feed or the previous. I have started designing the flow a bit.
Is it something that current users of the library will find useful ? If yes, I will get a PR ready in a short while.
Thanks.

Can't request me object: Hackney config

Hi.

I have followed the instructions to get my user's basic info, and I'm getting a missing Hackney config error. These are the steps I'm taking:

1. Install the dependency

{:facebook, "~> 0.20.0"}

2. Create my own Facebook app and get an access token

3. When I try to follow the example, I get

 Facebook.me("name,first_name", TOKEN)
=> ** (ArgumentError) argument error
    (stdlib) :ets.lookup_element(:hackney_config, :mod_metrics, 2)
    /app/deps/hackney/src/hackney_metrics.erl:27: :hackney_metrics.get_engine/0
    /app/deps/hackney/src/hackney_connect.erl:69: :hackney_connect.create_connection/5
    /app/deps/hackney/src/hackney_connect.erl:37: :hackney_connect.connect/5
    /app/deps/hackney/src/hackney.erl:316: :hackney.request/5
    lib/httpoison/base.ex:439: HTTPoison.Base.request/9
    lib/facebook.ex:174: Facebook.me/2

Am I missing some configuration?

HTTPPosion version bump

Any plans to start using httppoison at leat to 1.0? 0.13 is a bit old and brings inconsistency to project.

Unable to read env key

I'm having the following error:
** (RuntimeError) unable to read env key: appsecret for app: facebook lib/facebook/config.ex:2: Facebook.Config.get_env/1 lib/facebook.ex:71: Facebook.me/2

Even after setting the environment variable in a .env file, and setting the config.exs like so:

config :facebook, Users.Facebook, appsecret: System.get_env("FB_ACCESS_TOKEN")

Any advice?

Error when request to Graph API

I request to /me

fields = ["name", "birthday", "first_name", "last_name", "address", "gender", "email"]
Facebook.me(fields, access_token)

But it raise an error:

[error] #PID<0.1058.0> running App.Endpoint terminated
Server: localhost:80 (http)
Request: POST /api/users/fb_sign_in
** (exit) an exception was raised:
    ** (UndefinedFunctionError) undefined function: :hmac.hexlify/2 (module :hmac is not available)
        :hmac.hexlify(<<101, 133, 65, 126, 95, 129, 67, 126, 54, 42, 27, 31, 160, 99, 106, 211, 84, 26, 178, 44, 77, 212, 157, 80, 223, 244, 216, 36, 8, 154, 254, 179>>, [:string, :lower])
        lib/facebook.ex:79: Facebook.me/3
        (app) web/controllers/api/user_controller.ex:31: App.Api.UserController.fb_sign_in/2
        (app) web/controllers/api/user_controller.ex:1: App.Api.UserController.action/2
        (app) web/controllers/api/user_controller.ex:1: App.Api.UserController.phoenix_controller_pipeline/2
        (app) lib/phoenix/router.ex:255: App.Router.dispatch/2
        (app) web/router.ex:1: App.Router.do_call/2
        (app) lib/app/endpoint.ex:1: App.Endpoint.phoenix_pipeline/1
        (app) lib/plug/debugger.ex:90: App.Endpoint."call (overridable 3)"/2
        (app) lib/phoenix/endpoint/render_errors.ex:34: App.Endpoint.call/2
        (plug) lib/plug/adapters/cowboy/handler.ex:15: Plug.Adapters.Cowboy.Handler.upgrade/4
        (cowboy) src/cowboy_protocol.erl:442: :cowboy_protocol.execute/4

Document Getting Started

An example of usage would be really nice, e.g.

Facebook.me("name,birthday,first_name,last_name,address,gender,email", "<your access token>")

Also (and maybe this is obvious to a non-beginner like me), I needed to install httpoison as per the instructions here:

https://github.com/edgurgel/httpoison#installation

PROPOSAL - Add extendable usage

Hello, Facebook API is huge and you can't cover all things in your lib. So I think it would be nice to make it extendable. Like this:
project_name/lib/project_name/api_wrappers/facebook.ex

defmodule ProjectName.ApiWrappers.FacebookApi do
  use Facebook # your lib

  def my_custom_api_call(args) do
    HTTPoison.get ...
  end
end

As a result, we can use your lib API along with our custom.

Looking for a new maintainer

I'm not using this library since a while now and that's also the reason why there's not much activity going on.
I'd be glad if someone could take over maintenance which uses the library.

Maybe @bugant?

Configuration sample

Hello I followed the example in the readme but I got this error.

** (ArgumentError) application :facebook is not loaded, or the configuration parameter :appsecret is not set
    (elixir) lib/application.ex:281: Application.fetch_env!/2
    lib/facebook.ex:488: Facebook.add_app_secret/2
    lib/facebook.ex:73: Facebook.me/2

Please can you provide a sample mix configuration.

"Invalid verification code format."

Please how do i get the code passed to the accessToken function? I can't seems to figure out what the code is.

Where do I set the App ID ?

Hello, sorry if this is not the right place to ask,

I see how to set the App Secret
but nothing about the App ID ?

how does this work?

thanks