This article contains a “checklist” of integration best practices and requirements for becoming part of the C2C ecosystem. Not all requirements will apply to all integrations. You’ll be able to work with our team to decide what requirements apply to your particular!
The following is required of all integrations:
- Displays connected project name to user when connected: Enables the user to quickly double-check what project they are connected to without scouring Frame.io’s UI.
Simple Upload Status
- Number of files remaining
- Total file size Remaining
- Progress of current file upload: Gives confidence to user that files are being uploaded.
- Displays network connection status
- Automatically refreshes access token after 8 hour expiration with no interaction / alert to the user. No user interaction failures or errors should occur because of an expired token, unless there is an error refreshing the token.
- Can back out or cancel authorization flow. A user may decide they are not ready connect after initiating authorization flow. The application or device must have an affordance for cancelling authorization at each step of the process.
Application integrations must meet the following additional requirements:
Displays current login information. The following information must be displayed to verify the currently logged in user:
- Optional: Profile Image
- Implements a Frame.io connection manager: explained below
We want to make sure that configuring the C2C connection is as seamless as possible for the user. To help accomplish this, we require that application integrators’ UIs have a dedicated area to manage their C2C connection and check its status. This section is not required to be its own page, but is required to contain the connection state, and is the natural place that a user would go to initiate the authorization flow.
The following states should be accounted for:
- Not Authorized: If a user is not logged to Frame.io, there must be a Call to Action to prompt them to initiate the authorization flow.
Not Connected: Once the user has authenticated, they need to select a project.
- Account Listing/Selection. Users can be part of multiple accounts, so they need to be able to narrow which account they are looking for their project in.
- Project Listing/Selection: Once a user has selected an account, a list of projects for that account needs to be displayed.
- OPTIONAL: The list of projects can get quite large, so a simple search / filter functionality goes a long way to make finding the right project easier.
- Display the name of the project they are connected to.,
- Ability for the user to disconnect from the current project.
- Ability for the user to choose a new project.
Here at Frame.io take security very seriously, and that extends to our integrators.
- Makes all requests over HTTPS. HTTP requests will be rejected by our server.
- Integrations must make a direct connection to Frame.io from the physical device or application, and may not pass through an intermediary service provider.
client_idmust not be accessible via users.
refresh_tokencredentials must not be accessible via users.
- OPTIONAL: Stored secrets and tokens should be encrypted at rest.
The most complicated part of any integration will be reliably uploading Frame.io with all created media over a variety of bad states.
We require integrations gracefully handle the following scenarios:
- Clearly and easily displays upload status to the user.
- Writes files to permanent or removable local storage. This storage must be accessible to the user.
Maintains an upload Queue that ensures delivery of files to Frame.io if:
- Another file(s) is currently uploading
- There is currently no network connectivity: uploads should resume when network is re-established
- The camera is power cycled before/during an upload
Will retry failed uploads if:
- Network connectivity lost or unstable
- Power cycle initiated
- A non-fatal error is encountered:
- Request timeout
- Network Error
- Token Expired
- Respects PAUSED status, and will not upload any filed until after the device has been RESUMED.
- Handles non-fatal AWS errors: click here for more information.
- Handles poisoned media (media that will always fail to upload). Retry logic should be able to detect and filter out bad media that will always result in an error. Such media should not block other media from being uploaded.
- Capable of uploading files at no less than 50Mbps, external network conditions notwithstanding. Users will expect upload speeds to match network speeds, with 50Mbps being a hard floor for what users will find acceptable.
- Capable of WiFi connectivity and support no less than WPA2 security. Ethernet connectivity is not required.
- Capable of both DHCP and Static IP configurations.
- Capable of clearly and easily displaying network status to the user.
Good testing leads to great software! Because C2C is designed to be used in the most suboptimal conditions imaginable, we put some requirements on our integrations for testing.
Tested using network configurations consisting of at least the following scenarios. Each scenario should be tested for WiFi, Ethernet, and USB if the Device supports hardline connections. Each scenario should also be tested for various traffic conditions.
- Commercial router connected to a hardline WAN (ie, typical home or small office).
- Commercial router connected to bonded cellular (ie, multi-SIM) modem.
- Commercial router connected to commercial cellular modem.
- Commercial router connected to commercial hotspot-style modem (ie, USB or WiFi only).
- Directly connected to bonded cellular (ie, multi-SIM) modem.
- Directly connected to commercial cellular modem.
- Directly connected to commercial hotspot-style modem (ie, USB or WiFi only). Both USB and WiFi connectivity should be tested if the Device supports a USB modem.
- Directly connected to a cellphone in hotspot mode.
- Tested with unexpected / random power outages.
- Tested with unexpected / random network disconnections.
- Tested with poisoned media (corrupted file or other error that will always result in an upload error).
The Frame.io Camera to Cloud API and eco-system is a living product. The features we have today will certainly not be the same features we have in the future. We will always maintain backwards compatibility so that your integration continues to operate without any changes.
We know that our roadmap will not always line up with yours, so our ask is that we keep an open dialogue in regards to future developments to ensure that we can keep our API up to date with the way it is being used!
Throw a mortarboard in the air, because you’ve just graduated from the UC2CIG (University of C2C Integration Guides)! We hope you found this series informative!
Please let us know if you feel anything is missing or confusing in these guides, or with any other C2C-related questions and troubleshooting. We are here to help!