Building a Box web app integration with Vercel
While perusing the Box web app, you may have noticed that if you click on the ellipsis button to the right of a file or folder, there is an option in the dropdown labeled integrations. Hovering over that selection reveals another dropdown with a list of built in actions that can be triggered off the content selected. For example, a user can simply click “Send with Gmail” and a shared link for the content can be emailed to another party.
At Box, we call these options Web App Integrations. In addition, if you click on the Apps tab in the left menu bar, you can find a whole host of public integrations to choose from. But, before being placed into our App Center, you need to develop and setup the integration. In today’s post, I’m going to walk you through doing just that!
Let’s go!
Web app integration overview
Web app integrations or service actions, allow third-party or custom built applications by any developer to become part of the Box user experience, allowing users to alter or use content beyond just viewing it in the Box web app. With a service action, users can share, edit, or view details about the content which triggers the integration.
Box offers what we call a popup integration, meaning the solution will appear in a popup window outside of the main Box Web App. All the code for the integration needs to be hosted and maintained in a separate location from Box.
When the integration is triggered, any parameters configured, like file id or file extension, are sent over to the url to be processed. An auth code parameter can also be sent, which can be used to request an access token from Box to make further API calls. To find out more about the parameter options, please visit that section in our guides.
Common use cases
We’ve seen Box customers use this functionality for several different use cases, including sending a shared link via Gmail, sharing a file on Slack, sending a document for signature on DocuSign or Adobe, creating a pdf with Adobe, and many more! Web app integrations reduce manual overhead to achieve a common task related to content already in Box.
Walkthrough
To build a web app integration, you need to create a Box app, configure that application as a web app integration, deploy custom code to a third party hosting provider, test, and publish. Optionally, you can submit your integration to the Box App Center.
For this demo, I’m going to demonstrate a very simple example —exchanging the auth code for a token and renaming the file that triggered the integration. And yes — you absolutely can rename a file in the main Box Web App, but to show you the art of the possible, this demo shows how you can not only use but also change the content that triggers the integration. Use this walkthrough as a jumping off point to start your own development.
Before following along, please note that this example should be deployed in a sandbox or developer environment. For ease and quickness, I store a token in the browser — which is not the most secure. In your own implementations, you will want to follow your own organizations security policies.
Setup a Box app
From the Box Developer Console, click create new app, followed by selecting the custom app option.
Give the application a name, and select the required options. Click next.
Select User Authentication (OAuth 2.0) and click create app.
On the configuration tab, make sure the read/write all files and folders options are checked. Click save changes in the top right.
Before configuring the integration tab, we need to deploy some custom code that will appear in the popup.
Deploy custom code
The completed code for this demo is located at this GitHub repository. For simplicity, I am using Vercel to create a small web server. If you scroll down the README, you will find a deploy button. Click it.
If you don’t have a Vercel account, create one by clicking one of the Git providers. If you do, log in. I’m going to use GitHub.
First, you’ll need to create a GitHub repo for the code to be cloned to. This is also helpful if you want to make customizations after the demo. Name the repo and click create.
Next, we will add the client id and client secret from the Box app we created in the last step. Fill in the respective boxes, and click deploy.
Once complete, you should see this screen. At this point, we have a web app deployed to the cloud! We can now use this app in tandem with Box.
Click continue to dashboard, followed by the visit button in the top right. Copy the deployment url from the url bar. We will use this in the next Box configuration step.
If you’d like more of a deep dive on how the repo is setup or how the app works, please see the readme in the GitHub repo.
Configure web app integration
On the integrations tab of your app in the Box Developer Console, click create a web app integration.
Now, we need to fill out all the pieces of information related to our app. Add a name and description. As you move down the page, I left all of these as the default choices, but depending on your use case beyond this demo, you may need to change them.
Add the deployment url to the client callback url box. Add a prompt message. Then, continue down the page.
In the callback parameters section, we need to add a few options. In order for the deployed code to work, you’ll want to match my naming conventions exactly. I added four get method parameters: file_id, file_extension, redirect_uri, and auth_code. I selected their respective option in the dropdown to the right.
Box provides two methods for web app integrations: get and post. If using the post method, your web server will need to accept a post request. Otherwise, get method parameters will appear in the url, example: http://your-client-callback-url.com/?get_param1=value1. Find out more in our guides. For now, leave the integration status in development. Click save changes in the top right.
You should see a success message, and the page should reload to this screen. In the future, you can edit the integration by clicking the edit button.
Test
So far, we have created a Box app, deployed a small web app to Vercel, and configured the web app integration in Box. Now, we can test it out!
Open a folder in Box. Select a file, and click the ellipsis button. Click on the web app integration test option. Remember — since the web app integration is in development mode, only the developer(s) tied to Box app can see it.
A popup will appear with the application that we deployed to Vercel. You should see the file id, file extension, auth code, and access token. I included this information for demo and testing purposes, but you would probably not want to expose tokens or code in this way in the real world.
In the text box, type in a new file name. Click rename file.
If successful, the popup should automatically close. If you reload the Box page (cmnd+R on mac), your file should now be renamed. Ta-da!
Publish
After adequate testing, you can open up the web app integration to other users, by changing the status in the integration configuration tab.
Submit for Box App Center (optional)
After you have developed and tested a web app integration, you can submit the application to the Box App Center but filling out the information in the App Center tab. Our internal integration team will then review and engage with you on publishing the application.
Closing Thoughts
As you can see from above, deploying a small web app to a service like Vercel, connecting it to Box, and using it in tandem with content in Box is super easy.
While this example is very simple, you should be able to take this idea and expand it for other specific use cases.
Happy Coding!
Resources
GitHub Repo
As always, if you have any feedback for the Box Developer Relations team, feel free to drop us a line on the developer forum.
