Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: make hosted Companion more clear #5394

Merged
merged 2 commits into from
Aug 15, 2024
Merged

docs: make hosted Companion more clear #5394

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0875431
docs: make hosted Companion more clear
Murderlon Aug 8, 2024
1ea4980
Fix missing definition
Murderlon Aug 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/companion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,42 @@ files to arrive at Transloadit servers, much like Uppy.

:::

To do so each provider plugin must be configured with Transloadit’s Companion
URLs:

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Dropbox from '@uppy/dropbox';

uppy.use(Dropbox, {
companionUrl: COMPANION_URL,
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should also line out what actual values can be inserted for COMPANION_URL

People often don't get this.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should also line out what actual values can be inserted for COMPANION_URL

The idea is that folks do not insert actual values, but import it from @uppy/transloadit

Copy link

@cdr-chakotay cdr-chakotay Aug 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, personally I know that. But our customers are sometimes overwhelmed and do not get it managed (somehow).

companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});
```

You may also hit rate limits, because the OAuth application is shared between
everyone using Transloadit.

To solve that, you can use your own OAuth keys with Transloadit’s hosted
Companion servers by using Transloadit Template Credentials. [Create a Template
Credential][template-credentials] on the Transloadit site. Select “Companion
OAuth” for the service, and enter the key and secret for the provider you want
to use. Then you can pass the name of the new credentials to that provider:

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Dropbox from '@uppy/dropbox';

uppy.use(Dropbox, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
companionKeysParams: {
key: 'YOUR_TRANSLOADIT_API_KEY',
credentialsName: 'my_companion_dropbox_creds',
},
});
```

## Installation & use

Companion is installed from npm. Depending on how you want to run Companion, the
Expand Down Expand Up @@ -949,3 +985,5 @@ automatically restart when files are changed.
[url]: /docs/url
[zoom]: /docs/zoom
[transloadit]: https://transloadit.com
[template-credentials]:
https://transloadit.com/docs/#how-to-create-template-credentials
38 changes: 38 additions & 0 deletions docs/sources/companion-plugins/box.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,41 @@ new Uppy()
.use(Box, { companionUrl: 'https://your-companion.com' });
```

### Use with Transloadit

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Box from '@uppy/box';

uppy.use(Box, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});
```

You may also hit rate limits, because the OAuth application is shared between
everyone using Transloadit.

To solve that, you can use your own OAuth keys with Transloadit’s hosted
Companion servers by using Transloadit Template Credentials. [Create a Template
Credential][template-credentials] on the Transloadit site. Select “Companion
OAuth” for the service, and enter the key and secret for the provider you want
to use. Then you can pass the name of the new credentials to that provider:

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Box from '@uppy/box';

uppy.use(Box, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
companionKeysParams: {
key: 'YOUR_TRANSLOADIT_API_KEY',
credentialsName: 'my_companion_dropbox_creds',
},
});
```

### Use in Companion

You can create a Box App on the
Expand Down Expand Up @@ -186,3 +221,6 @@ export default {
},
};
```

[template-credentials]:
https://transloadit.com/docs/#how-to-create-template-credentials
38 changes: 38 additions & 0 deletions docs/sources/companion-plugins/dropbox.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,41 @@ new Uppy()
.use(Dropbox, { companionUrl: 'https://your-companion.com' });
```

### Use with Transloadit

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Dropbox from '@uppy/dropbox';

uppy.use(Dropbox, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});
```

You may also hit rate limits, because the OAuth application is shared between
everyone using Transloadit.

To solve that, you can use your own OAuth keys with Transloadit’s hosted
Companion servers by using Transloadit Template Credentials. [Create a Template
Credential][template-credentials] on the Transloadit site. Select “Companion
OAuth” for the service, and enter the key and secret for the provider you want
to use. Then you can pass the name of the new credentials to that provider:

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Dropbox from '@uppy/dropbox';

uppy.use(Dropbox, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
companionKeysParams: {
key: 'YOUR_TRANSLOADIT_API_KEY',
credentialsName: 'my_companion_dropbox_creds',
},
});
```

### Use in Companion

You can create a Dropbox App on the
Expand Down Expand Up @@ -186,3 +221,6 @@ export default {
},
};
```

[template-credentials]:
https://transloadit.com/docs/#how-to-create-template-credentials
38 changes: 38 additions & 0 deletions docs/sources/companion-plugins/facebook.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,41 @@ new Uppy()
.use(Facebook, { companionUrl: 'https://your-companion.com' });
```

### Use with Transloadit

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Facebook from '@uppy/facebook';

uppy.use(Facebook, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});
```

You may also hit rate limits, because the OAuth application is shared between
everyone using Transloadit.

To solve that, you can use your own OAuth keys with Transloadit’s hosted
Companion servers by using Transloadit Template Credentials. [Create a Template
Credential][template-credentials] on the Transloadit site. Select “Companion
OAuth” for the service, and enter the key and secret for the provider you want
to use. Then you can pass the name of the new credentials to that provider:

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Facebook from '@uppy/facebook';

uppy.use(Facebook, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
companionKeysParams: {
key: 'YOUR_TRANSLOADIT_API_KEY',
credentialsName: 'my_companion_dropbox_creds',
},
});
```

### Use in Companion

You can create a Facebook App on the
Expand Down Expand Up @@ -183,3 +218,6 @@ export default {
},
};
```

[template-credentials]:
https://transloadit.com/docs/#how-to-create-template-credentials
38 changes: 38 additions & 0 deletions docs/sources/companion-plugins/google-drive.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,41 @@ new Uppy()
.use(GoogleDrive, { companionUrl: 'https://your-companion.com' });
```

### Use with Transloadit

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import GoogleDrive from '@uppy/google-drive';

uppy.use(GoogleDrive, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});
```

You may also hit rate limits, because the OAuth application is shared between
everyone using Transloadit.

To solve that, you can use your own OAuth keys with Transloadit’s hosted
Companion servers by using Transloadit Template Credentials. [Create a Template
Credential][template-credentials] on the Transloadit site. Select “Companion
OAuth” for the service, and enter the key and secret for the provider you want
to use. Then you can pass the name of the new credentials to that provider:

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import GoogleDrive from '@uppy/google-drive';

uppy.use(GoogleDrive, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
companionKeysParams: {
key: 'YOUR_TRANSLOADIT_API_KEY',
credentialsName: 'my_companion_dropbox_creds',
},
});
```

### Use in Companion

To sign up for API keys, go to the
Expand Down Expand Up @@ -187,3 +222,6 @@ export default {
},
};
```

[template-credentials]:
https://transloadit.com/docs/#how-to-create-template-credentials
38 changes: 38 additions & 0 deletions docs/sources/companion-plugins/google-photos.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,41 @@ new Uppy()
});
```

### Use with Transloadit

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import GooglePhotos from '@uppy/google-photos';

uppy.use(GooglePhotos, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});
```

You may also hit rate limits, because the OAuth application is shared between
everyone using Transloadit.

To solve that, you can use your own OAuth keys with Transloadit’s hosted
Companion servers by using Transloadit Template Credentials. [Create a Template
Credential][template-credentials] on the Transloadit site. Select “Companion
OAuth” for the service, and enter the key and secret for the provider you want
to use. Then you can pass the name of the new credentials to that provider:

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import GooglePhotos from '@uppy/google-photos';

uppy.use(GooglePhotos, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
companionKeysParams: {
key: 'YOUR_TRANSLOADIT_API_KEY',
credentialsName: 'my_companion_dropbox_creds',
},
});
```

### Use in Companion

To sign up for API keys, go to the
Expand Down Expand Up @@ -183,3 +218,6 @@ export default {
},
};
```

[template-credentials]:
https://transloadit.com/docs/#how-to-create-template-credentials
38 changes: 38 additions & 0 deletions docs/sources/companion-plugins/instagram.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,41 @@ new Uppy()
.use(Instagram, { companionUrl: 'https://your-companion.com' });
```

### Use with Transloadit

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Instagram from '@uppy/instagram';

uppy.use(Instagram, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});
```

You may also hit rate limits, because the OAuth application is shared between
everyone using Transloadit.

To solve that, you can use your own OAuth keys with Transloadit’s hosted
Companion servers by using Transloadit Template Credentials. [Create a Template
Credential][template-credentials] on the Transloadit site. Select “Companion
OAuth” for the service, and enter the key and secret for the provider you want
to use. Then you can pass the name of the new credentials to that provider:

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import Instagram from '@uppy/instagram';

uppy.use(Instagram, {
companionUrl: COMPANION_URL,
companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
companionKeysParams: {
key: 'YOUR_TRANSLOADIT_API_KEY',
credentialsName: 'my_companion_dropbox_creds',
},
});
```

### Use in Companion

To sign up for API keys, go to the
Expand Down Expand Up @@ -196,3 +231,6 @@ export default {
},
};
```

[template-credentials]:
https://transloadit.com/docs/#how-to-create-template-credentials
Loading
Loading