User Guide: OONI Run

Last updated: 13th December 2022

OONI Run

OONI Run is a web platform that you can use to generate mobile deep links and widget code to coordinate OONI Probe website testing. Specifically, you can use OONI Run to create links or widget code for:

OONI Run links only work with the OONI Probe mobile app. To learn how to use OONI Probe, please refer to our OONI Probe mobile app user guide.

This user guide provides step-by-step instructions on how to use the OONI Run platform for custom OONI Probe website testing.

What you will get from this guide:

Upon reading this guide, we hope you will feel empowered to share your OONI Run knowledge and skills with others! We also hope this guide helps with coordinating OONI Probe website testing around the world.

The following table of contents should help with navigating the guide.

OONI Run enables you to generate a link to test websites (of your choice) for censorship. You can also share this link with other [OONI Probe mobile app users so that they can test those websites. The first step is to determine which websites you want to test.

Step 1. Create a list of websites in a text editor, where each URL is in a separate line. You do not need to separate URLs by commas or in any other way. Please see an example below.

List of URLs

Important: Please ensure that each URL is typed correctly. If it is mis-typed, OONI Probe will not test the intended website and this will potentially lead to inaccurate test results.

A few things to keep in mind:

To ensure that each URL is typed accurately, please copy-paste it from a browser.

If you don’t have specific websites in mind, you can refer to the public lists ("test lists") that OONI Probe uses for testing. These lists include a wide range of websites, all of which are thematically categorized (e.g. news media, human rights).

Step 2. Copy your list of URLs (from your text editor).

Step 3. Visit the OONI Run website: https://run.ooni.io/

OONI Run

Step 4. Paste your list of URLs into the first URL slot of the OONI Run page.

You should now see that all of your URLs have populated each URL row in the OONI Run page.

List of URLs

If you notice any empty rows (or otherwise misformatted URLs), please delete them by clicking on the deletion icon or edit them by clicking on the URL field.

Step 5. Click the Generate button at the end of your list.

Generate OONI Run link

You will now see the following pop-up window.

Pop-up window

You have generated an OONI Run mobile deep link for the testing of your list of websites.

Step 1. An OONI Run link can only be used with the OONI Probe mobile app. Please install the OONI Probe mobile app. It’s available for Android, F-Droid and iOS.

OONI Prome mobile app

Step 2. Copy the link generated in the previous section either by:

Copy link address

Step 3. As you’re probably doing all these steps from your desktop, share the copied link with your mobile phone (so that you can subsequently open the link with your OONI Probe mobile app). Unfortunately, it’s not currently possible to use OONI Run links with the OONI Probe Desktop app.

You can also share this link with other OONI Probe mobile app users, if you would like them to test your list of websites as well.

Step 4. Tap on the OONI Run link from your mobile device.

OONI Run link

Step 5. Open the link with your OONI Probe mobile app (not with a web browser).

Open with OONI Probe

You should now see your list of websites in your OONI Probe mobile app.

List of websites

Step 6. Tap Run to test your list of websites. Depending on the length of your list and the performance of the network you’re connected to, the test runtime may vary. If the test takes too long and you would like to terminate it, you can stop the ongoing test by tapping the cross button at the top of the screen.

Run test

Once you complete the testing based on an OONI Run link, your OONI Probe test results will automatically get published on OONI Explorer and on the OONI API in near real-time. You will also have immediate access to your test results through the OONI Probe mobile app.

To learn more about accessing and sharing OONI Probe test results, please refer to our OONI Probe mobile app user guide.

Creating OONI Run widget code for website testing

Instead of sharing OONI Run links, you can generate OONI Run widget code, which you can embed into your website to encourage (long-term) OONI Probe testing of websites that you care about.

For example, we have embedded several OONI Run widgets into our website to enable community members to more easily test specific websites (such as social media, news media, and VPN websites). This is often easier than sharing OONI Run links every time.

OONI Run widgets

Below we share an example of how our partner, Sinar Project, embedded OONI Run widgets into their website to encourage the testing of specific websites during Malaysia’s 2022 general election.

Sinar example

To create your own OONI Run widget:

Step 1. When generating an OONI Run link (see section on “Creating OONI Run links”), the pop-up window will also generate widget code for the testing of the websites that you added to the OONI Run platform. This widget code is highlighted in the image below.

Widget code

Step 2. You can embed an OONI Run widget into your website as a simple button or as a tall banner.

If you would like to add an OONI run button on your website, you can copy and paste the widget code from the pop-up window. For a simple button use the <a href under the /* For a simple button */ section, or if you would prefer to add a banner, use the code after the /* For a tall banner */ section.

You will also have to include the widget script code, generally in the base layout of your website:

/* If you have not already included the OONI widget code */
<script src='https://cdn.jsdelivr.net/npm/ooni-run/dist/widgets.js'></script>

By default, the button will say “Run OONI!” but you can change this text by editing Run OONI! in the code. The banner will say “Fight Censorship” but you can change that by editing Fight Censorship in the code.

Optional, but encouraged: Adding your websites to test lists

If some of the websites that you used for OONI Run links or widget code are relevant for country-wide or worldwide testing, please propose them for the lists of websites ("test lists") tested by all OONI Probe users. You can do so through our Test Lists Editor.

Test Lists Editor

Please refer to our guide to learn how to update test lists using the Test Lists Editor.