README.md

Fresco

The Fresco project aims to bring Network Canvas interviews to the web browser. It is a pilot project that does not add new features to Network Canvas, but rather provides a new way to conduct interviews.

Known Issues

• Custom node label workers are not implemented.
• Videos and audio cannot autoplay on first load due to browser limitations. Participants must have interacted with the interview before media can autoplay.
• The 'Use fullscreen forms' visual preference is not supported.
• When exporting data, the "use screen layout coordinates" feature uses a hardcoded screen size of 1920 x 1080. Please note that this does not correspond to the screen size used by your participants.

Deployment Guide

Step 1

Create a new app on UploadThing to store media files

Fresco uses your UploadThing account to store protocol assets, exported files, etc.

1. Go to uploadthing.com.

2. Click on the "Get started" button.

   

3. Sign in to your account via Github (If you don't have a Github account, this will prompt you to create one).

   

4. Authorize UploadThing.

   

5. You will be prompted to your dashboard. Click on "Create a new app" button.

   

6. Create your app by giving it a name in the "App Name" section and hit "Create App".

   

7. On your dashboard, go to "API Keys" section from the sidebar navigation and copy your API keys (make sure to save them in a safe place as they are required to deploy Fresco on Vercel).

   

For more info, check out UploadThing Docs.

Step 2

Fork Fresco Repository

Prerequisite: You need to have a GitHub account. Go to GitHub and sign up for an account if you do not already have one.

1. On this repository, click the Fork button

   

2. Create your Fork

Enter a repository name (this will be your Fresco instance name), description (optional), and click Create Fork.

This will create a separate instance of the Fresco repository that you can deploy.

Step 3

Deploy Forked Repository on Vercel

Prerequisite: You need to have a Vercel account. Go to vercel.com and sign up for an account.

Sign in to Vercel via your Github account so that you can easily connect your repositories. You can use their "Hobby" tier or paid plan.

1. Create a new Project

2. Import Git Repository

Find your Fresco instance from the list of your git repositories and click Import.

3. Configure Project.

   Copy the template below and paste it into the Environment Variables section in Vercel to prepopulate the form with the required environment variables.

   Replace the values with your environment variable values from the services you set up in Step 1 and Step 2.

UPLOADTHING_SECRET=your_uploadthing_api_key
UPLOADTHING_APP_ID=your_uploadthing_app_id
DISABLE_ANALYTICS=false

Variable Key	Description
UPLOADTHING_SECRET	The API key for your UploadThing app. This is used to authenticate requests from Fresco to the UploadThing API. More info
UPLOADTHING_APP_ID	The unique identifier for your UploadThing app. This is used along with the secret key to identify your app when making requests from Fresco to the UploadThing API. More info
DISABLE_ANALYTICS	A flag to disable the analytics microservice for Fresco. If this is set to false, the analytics microservice will be enabled.

NOTE: We use analytics to gather error data from instances of Fresco to troubleshoot issues. By leaving DISABLE_ANALYTICS set to false (the default) you will help us identify bugs and improve the app.

NOTE: When entering the environment variables, do not include the variable keys in the inputs(e.g: UPLOADTHING_SECRET=). You should enter the value of the variable which starts after = symbol (e.g: sk_live_xxxx)

Also, when providing the environment variables, do not enclose the variable values in quotes. For example:

✅ Correct: sk_live_xxxxxxxxxxxxxxxxxxx

❌ Incorrect: 'sk_live_xxxxxxxxxxxxxxxxxxx'

4. Deploy

   Click "Deploy" and wait for the deployment to finish.

   NOTE: If you encounter any issues during deployment, check out the Troubleshooting section or our User Community for a possible solution.

5. Visit your deployed Fresco app by clicking on the preview or go to your dashboard by clicking "Continue to Dashboard" button...

   

   ...and click on one of the domains names or the "Visit" button on the right corner.

   

Step 4

Create your database

1. From your project dashboard, select Storage. Then, select Create within the Postgres row.

2. Review and accept the terms in the modal.

3. Give your database a name and select the region that is closest to where you and your participants will be located. Then, click Create. Your database will be generated and you will be redirected to the Getting Started page.

4. You will be prompted to connect your project. Select Connect.

5. Select the Deployments tab. Click on the menu beside the most recent deployment and select Redeploy. This will redeploy your project with your new connected database.

Create User Account on Your Fresco App

Visit your deployed app to create your administrator account. Only one user account can be created.

NOTE: For security, you have 30 minutes from when the app is deployed to create a user account. If this time elapses without a user account being created, your configuration will expire. You would have to Trigger Redeployment on Your App by Resetting Your Database.

1. Create an account by providing a username and password.

   

2. Upload a protocol (this step can be skipped as you can always upload protocols from the dashboard later).

   

3. Configure participation.

   • Import participants (this is optional as you can always import/add participants from the dashboard later).
   • Allow anonymous recruitment (this enables your participants join your study by visiting a URL).

   

4. Click the "Go to the dashboard" button and begin your exciting exploration of Fresco.

For more info, check out our User Community.

Troubleshooting

Deployment Build Errors and Fixes

• If you encountered the "Invalid API key" error...

  

  It means that you provided an incorrect environment variable. Make sure to enter the environment variable value correctly. You must enter the value that starts after = symbol (e.g: UPLOADTHING_APP_ID=5q5ybg9dwg, here UPLOADTHING_APP_ID is the key of variable and 5q5ybg9dwg is the value. You should always enter the value)

Instance Expired - Reset your Database

If your instance expires, you must delete your database and create a new one.

1. Navigate to your database on the dashboard by selecting Storage and then selecting your database.

   

2. Select the Projects tab, check the box next to your project, and select Remove Project Connection from the dropdown.

   

3. Select Remove Connection to confirm.

   

4. Select the Settings tab and select Delete Database from the Delete Store section.

   

5. After confirming, you can follow the instructions again to Create a Database

Upgrade Guide

Fresco is Alpha software and will be continuously improved. As we release updated versions of Fresco, you can upgrade your deployed instance using this guide.

Step 1

Sync Fork

From your GitHub repository, click Sync Fork and select Update Branch.

Vercel will automatically begin redeploying your Fresco instance. This process will take a few minutes to complete.

FAQ

Where will announcements about releases be posted?

New versions of Fresco will be announced on our User Community.

Which browsers are supported?

Fresco is supported on latest version of Chrome, Safari, and Firefox. This applies to the backend user dashboard and the participant interview experience.