mirror of
https://github.com/transloadit/uppy.git
synced 2026-07-17 16:50:22 +00:00
187 lines
4.4 KiB
Text
187 lines
4.4 KiB
Text
---
|
||
slug: /facebook
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
|
||
import UppyCdnExample from '/src/components/UppyCdnExample';
|
||
|
||
# Facebook
|
||
|
||
The `@uppy/facebook` plugin lets users import files from their
|
||
[Facebook](https://www.facebook.com) account.
|
||
|
||
:::tip
|
||
|
||
[Try out the live example](/examples) or take it for a spin in
|
||
[StackBlitz](https://stackblitz.com/edit/vitejs-vite-zaqyaf?file=main.js).
|
||
|
||
:::
|
||
|
||
## When should I use this?
|
||
|
||
When you want to let users import files from their
|
||
[Facebook](https://www.facebook.com) account.
|
||
|
||
A [Companion](/docs/companion) instance is required for the Facebook plugin to
|
||
work. Companion handles authentication with Facebook, downloads the files, and
|
||
uploads them to the destination. This saves the user bandwidth, especially
|
||
helpful if they are on a mobile connection.
|
||
|
||
You can self-host Companion or get a hosted version with any
|
||
[Transloadit plan](https://transloadit.com/pricing/).
|
||
|
||
<Tabs>
|
||
<TabItem value="npm" label="NPM" default>
|
||
|
||
```shell
|
||
npm install @uppy/facebook
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="yarn" label="Yarn">
|
||
|
||
```shell
|
||
yarn add @uppy/facebook
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="cdn" label="CDN">
|
||
<UppyCdnExample>
|
||
{`
|
||
import { Uppy, Facebook } from "{{UPPY_JS_URL}}"
|
||
const uppy = new Uppy()
|
||
uppy.use(Facebook, {
|
||
// Options
|
||
})
|
||
`}
|
||
</UppyCdnExample>
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
## Use
|
||
|
||
Using Facebook requires setup in both Uppy and Companion.
|
||
|
||
### Use in Uppy
|
||
|
||
```js {10-13} showLineNumbers
|
||
import Uppy from '@uppy/core';
|
||
import Dashboard from '@uppy/dashboard';
|
||
import Facebook from '@uppy/facebook';
|
||
|
||
import '@uppy/core/dist/style.min.css';
|
||
import '@uppy/dashboard/dist/style.min.css';
|
||
|
||
new Uppy()
|
||
.use(Dashboard, { inline: true, target: '#dashboard' })
|
||
.use(Facebook, {
|
||
target: Dashboard,
|
||
companionUrl: 'https://your-companion.com',
|
||
});
|
||
```
|
||
|
||
### Use in Companion
|
||
|
||
You can create a Facebook App on the
|
||
[Facebook Developers site](https://developers.facebook.com/).
|
||
|
||
The app page has a “Redirect URIs” field. Here, add:
|
||
|
||
```
|
||
https://$YOUR_COMPANION_HOST_NAME/facebook/redirect
|
||
```
|
||
|
||
If you are using Transloadit hosted Companion:
|
||
|
||
```
|
||
https://api2.transloadit.com/companion/facebook/redirect
|
||
```
|
||
|
||
You can only use the integration with your own account initially. Make sure to
|
||
apply for production status on the app page before you publish your app, or your
|
||
users will not be able to sign in!
|
||
|
||
You need to set up OAuth in your Facebook app for Companion to be able to
|
||
connect to users’ Facebook accounts. You have to enable “Advanced Access” for
|
||
the `user_photos` permission. A precondition of that is “Business Verification”
|
||
which involves setting up a Meta Business Account and submitting documents to
|
||
prove business ownership.
|
||
|
||
Configure the Facebook key and secret. With the standalone Companion server,
|
||
specify environment variables:
|
||
|
||
```shell
|
||
export COMPANION_FACEBOOK_KEY="Facebook API key"
|
||
export COMPANION_FACEBOOK_SECRET="Facebook API secret"
|
||
```
|
||
|
||
When using the Companion Node.js API, configure these options:
|
||
|
||
```js
|
||
companion.app({
|
||
providerOptions: {
|
||
facebook: {
|
||
key: 'Facebook API key',
|
||
secret: 'Facebook API secret',
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
## API
|
||
|
||
### Options
|
||
|
||
#### `id`
|
||
|
||
A unique identifier for this plugin (`string`, default: `'Facebook'`).
|
||
|
||
#### `title`
|
||
|
||
Title / name shown in the UI, such as Dashboard tabs (`string`, default:
|
||
`'Facebook'`).
|
||
|
||
#### `target`
|
||
|
||
DOM element, CSS selector, or plugin to place the drag and drop area into
|
||
(`string` or `Element`, default: `null`).
|
||
|
||
#### `companionUrl`
|
||
|
||
URL to a [Companion](/docs/companion) instance (`string`, default: `null`).
|
||
|
||
#### `companionHeaders`
|
||
|
||
Custom headers that should be sent along to [Companion](/docs/companion) on
|
||
every request (`Object`, default: `{}`).
|
||
|
||
#### `companionAllowedHosts`
|
||
|
||
The valid and authorised URL(s) from which OAuth responses should be accepted
|
||
(`string` or `RegExp` or `Array`, default: `companionUrl`).
|
||
|
||
This value can be a `string`, a `RegExp` pattern, or an `Array` of both. This is
|
||
useful when you have your [Companion](/docs/companion) running on several hosts.
|
||
Otherwise, the default value should do fine.
|
||
|
||
#### `companionCookiesRule`
|
||
|
||
This option correlates to the
|
||
[RequestCredentials value](https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials)
|
||
(`string`, default: `'same-origin'`).
|
||
|
||
This tells the plugin whether to send cookies to [Companion](/docs/companion).
|
||
|
||
#### `locale`
|
||
|
||
```js
|
||
export default {
|
||
strings: {
|
||
pluginNameFacebook: 'Facebook',
|
||
},
|
||
};
|
||
```
|