Dropbox Platform developer guide
This is your goto reference for building great apps on the Dropbox Platform and sailing through the app review process. Be sure to also refer to the developer branding guidelines and terms and conditions as you design your app.
App permissions
When you start building an app on the Dropbox Platform, you'll need to create a Dropbox app in the App Console. As part of the process, you'll need to choose the right permission for your app. Your app's permission (sometimes referred to as access type in the documentation) determines what data your app can access in a user's Dropbox.
Drop-ins
Strictly speaking, this isn't a permission. When you use Drop-ins, your app only gets specific access granted by the user. In the case of the Chooser, your app will have access to files selected by the user. In the case of the Saver, the user will save files from your app to the location they choose. Because Drop-ins don't grant your app direct access to a user's Dropbox, using them doesn't require production approval like other permissions do.
Datastores only
Your app can only access data through the Datastore API. Datastores are special data structures which are stored separately from the filesystem. Your app won't be able to access any files in a user's Dropbox with this permission.
File type
The File type permission gives your app access to all files of a specific type (such as text or image files) across a user's entire Dropbox. You can choose any type appearing in the list below.
- Text files .applescript, .as, .as3, .c, .cc, .clisp, .coffee, .cpp, .cs, .css, .csv, .cxx, .def, .diff, .erl, .fountain, .ft, .h, .hpp, .htm, .html, .hxx, .inc, .ini, .java, .js, .json, .less, .log, .lua, .m, .markdown, .mat, .md, .mdown, .mkdn, .mm, .mustache, .mxml, .patch, .php, .phtml, .pl, .plist, .properties, .py, .rb, .sass, .scss, .sh, .shtml, .sql, .tab, .taskpaper, .tex, .text, .tmpl, .tsv, .txt, .url, .vb, .xhtml, .xml, .yaml, .yml, and files with no extension
- Documents .csv, .doc, .dochtml, .docm, .docx, .docxml, .dot, .dothtml, .dotm, .dotx, .eps, .fdf, .key, .keynote, .kth, .mpd, .mpp, .mpt, .mpx, .nmbtemplate, .numbers, .odc, .odg, .odp, .ods, .odt, .pages, .pdf, .pdfxml, .pot, .pothtml, .potm, .potx, .ppa, .ppam, .pps, .ppsm, .ppsx, .ppt, .ppthtml, .pptm, .pptx, .pptxml, .prn, .ps, .pwz, .rtf, .tab, .template, .tsv, .txt, .vdx, .vsd, .vss, .vst, .vsx, .vtx, .wbk, .wiz, .wpd, .wps, .xdf, .xdp, .xlam, .xll, .xlr, .xls, .xlsb, .xlsm, .xlsx, .xltm, .xltx, .xps
- Images .bmp, .cr2, .gif, .ico, .ithmb, .jpeg, .jpg, .nef, .png, .raw, .svg, .tif, .tiff, .wbmp, .webp
- Videos .3g2, .3gp, .3gpp, .3gpp2, .asf, .avi, .dv, .dvi, .flv, .m2t, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .ogv, .ogx, .rm, .rmvb, .ts, .vob, .webm, .wmv
- Audio files .aac, .aif, .aifc, .aiff, .au, .flac, .m4a, .m4b, .m4p, .m4r, .mid, .mp3, .oga, .ogg, .opus, .ra, .ram, .spx, .wav, .wma
- eBooks .acsm, .aeh, .azw, .cb7, .cba, .cbr, .cbt, .cbz, .ceb, .chm, .epub, .fb2, .ibooks, .kf8, .lit, .lrf, .lrx, .mobi, .opf, .oxps, .pdf, .pdg, .prc, .tebr, .tr2, .tr3, .xeb, .xps
With File type permission, your app sees a filtered view of a user's Dropbox containing only the files which match your selected type. All other files simply don't appear to your app through the API. That means faster performance because you don't spend time fetching information about files you don't need. Your app can see all the user's folders, and even create new folders, but can't move, copy, delete, or share folders (since they might contain files your app can't see).
Your app can also read and write datastores using the Datastore API.
App folder
A dedicated folder named after your app is created within the Apps folder of a user's Dropbox. Your app gets read and write access to this folder only and users can provide content to your app by moving files into this folder.Your app can also read and write datastores using the Datastore API.
Full Dropbox
You get full access to all the files and folders in a user's Dropbox, as well as permission to read and write datastores using the Datastore API.
Your app should use the least privileged permission it can. When applying for production, we'll review that your app doesn't request an unnecessarily broad permission based on the functionality provided by the app. If your app will require a broader permission based on functionality that is planned but not yet implemented, be sure to mention this in your production request.
Dropbox for Business apps
Apps that are linked to Dropbox for Business team admins have a different set of permissions, described in the Dropbox for Business API documentation.
Production approval
When you first create a Dropbox API app, it is given development status. Your app functions the same as any production status app except that it can only be accessed by up to 100 users. (You can enable this from your app's info page on the App Console by clicking Enable additional users.) Many apps such as for demos, hackathons, staging environments, and internal tools can stay in development status. However, if you'd like to open your app to more users, you'll need to apply for production status.
Applying for production status
If you want to share your app with the world, apply for production status from your app's info page, accessible via the App Console. Before applying for production, make sure your app adheres to the developer branding guidelines and terms and conditions. It will be rejected if it doesn't.
When you apply for production status, you'll be prompted for additional info, and your app will then be submitted to us for review. We'll review your app as quickly as possible to make sure it adheres to the above guidelines. Be descriptive! The more info you provide when applying, the faster we'll be able to approve your app.
Once your app is approved for production status, any number of Dropbox users can link to your app. Keep in mind that once your app has production status, you can't change its name or permission. Make sure you're comfortable with your app's configuration before applying. Remember, your app is required to adhere to the production status requirements even after it has been approved.
Features of great Dropbox Platform apps
This section includes many of the practices that great Dropbox Platform apps have in common. For the best possible user experience (and your own sanity), try to apply these to your own app as much as you can.
Have clear branding on your app
Specifically:
- Follow our developer branding guidelines.
- Don't imply that your app was endorsed, built by, or in partnership with Dropbox.
- Do mention that you're using the Dropbox service, though.
This is especially important when your app is similar to one of the official Dropbox clients. To avoid user confusion over who built what, please be extra careful to follow the three points above.
Use the minimum permissions you need
If your app only needs the user to select a single file so you can print/publish/post/share it, use the Chooser. It's the easiest way to integrate with Dropbox and simple for users to use as well. If you only need to access files created by your app, use an App Folder. Requesting Full Dropbox access to pick a file when you could use the Chooser isn't a good use of the permission.
Respect user privacy; have a privacy policy
You need to respect users' privacy when they give you access to their Dropbox. Be sure to include a clear privacy policy that's specific to your app and describes what your app will and won't do with user data.
Integrate Dropbox in both the free and paid versions of your app
We find that users are far more likely to upgrade to paid apps when they've already linked their Dropbox account to a free app. Use Dropbox to get more engaged users and offer Dropbox support in both the free and paid versions of your app.
If you're building a developer tool on top of Dropbox, your developers will need their own Dropbox app keys
While we encourage developers to use our official SDKs and libraries, we know there are a lot of different approaches to building frameworks and APIs. Regardless of how an app makes use of the Dropbox Platform, we need to know what that app is so we can let users know which apps are accessing their data. For that reason, if you provide software or services that wrap the Dropbox Platform for other developers to use, those developers must still sign up for their own Dropbox app key.
Use a single app key for each distinct app
If you build multiple apps, use one and exactly one key for each app you make. This makes it much easier for us to debug issues when they arise. That said, if you're just building the same app for different platforms (for example, iOS and Android), you can use the same key.
Be really careful if you're building sync
The best way to build file sync into your app is to use the Sync API. We recommend you avoid trying to implement sync on your own—it's really hard! Even the best efforts usually result in an implementation that has many edge cases and a potential for data corruption. Users are trusting you when granting access to their data so be very mindful when building sync and if you can avoid it, don't delete or modify data unless you absolutely have to.
Apps we don't allow on the Dropbox Platform
This section describes the types of apps that are not allowed on the Dropbox Platform. Our goal when we first wrote this list was to prevent you from being surprised or disappointed after putting a lot of passion and effort into a project that we can't approve for general use. It's a terrible conversation for everyone involved. This list isn't exhaustive; any apps that violate either of our developer Branding Guidelines or Terms and Conditions won't be approved.
If you feel like your app is an exception, please contact our developer support team.
Don't build apps that promote IP or copyright infringement
Just don't do it.
Don't copy material from other sites unless you have the right to do so
Dropbox requires that users have the right to store the stuff in their Dropbox. If the purpose of your app is to allow users to download content from other services without having the proper legal rights, we won't be able to approve it.
Don't build file sharing apps
Dropbox doesn't support building publicly searchable file sharing networks on top of Dropbox.
App metrics and error logs
The App Console provides details about how your app is using the Dropbox Platform and APIs.
The app metrics feature shows statistics on the number of users and activity of your app. You can use the app metrics in combination with your own logging and analytics to help track your app's usage and growth.
The error log viewer shows recent API calls that resulted in an error response from Dropbox which is useful for debugging. This includes errors caused by malformed API calls as well as rate limiting. There may be a small delay between the exception occurring and the error being shown in the error log viewer.