User Guide: OONI Run

Last updated: 18th November 2024

OONI Run

OONI Run is a web platform that you can use to generate links to coordinate OONI Probe website testing. Specifically, you can use OONI Run to create links 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.

Joining the platform

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 create an account on OONI Run platform:

Step 1. Click the “Log In To Create OONI Run Link” button.

Step 2. Add your email address in the Email slot.

Note: We do not store email addresses when you log in, but only when you create an OONI Run link. We store your email address so that when OONI Probe users receive an OONI Run link from you, they can trust it based on your email address (which is displayed in the OONI Run link you create). This can help reduce the risk of running malicious links.

Step 3. Click the “Send me the Link” button. This will send a link to your email address.

Step 4. Click the link (“Please login here”) sent to your email to log into the OONI Run v2 platform.

You have now logged into the OONI Run platform and can start creating OONI Run links. Here you can customise the title, description, timeframe and a list of URLs for testing. To do this, please use the following instructions:

Step 1. Add a title for your OONI Run link. Optionally, you can add translations for your title.

Note: This title will appear in the OONI Run link card that testers will install in their OONI Probe mobile app. We recommend using a short title which clearly communicates the type of testing performed. In the above example, we have added “Test social media” as a title because we aim to include social media websites for testing in our OONI Run link.

Step 2. Add a short description for your OONI Run link. Optionally, you can add translations.

Note: In the above example, we have specified the social media platforms that we plan to add to our OONI Run link, and which we’re asking OONI Probe mobile app users to test. We recommend specifying the tested platforms or adding other useful context that can help encourage testing.

Step 3. Add a (longer) description for your OONI Run link. This is an opportunity to communicate details about the testing, and why it’s important. Optionally, you can add translations.

Step 4. Add an expiration date for your OONI Run link.

Note: Determine the expiration date based on how long you would like OONI Probe users to have the ability to run your OONI Run link.

Step 5. Click “Add URL” to start adding URLs to your OONI Run link.

Adding URLs to the list

The next step is to determine which websites you want to test. While thinking about the list of websites you want to share with other OONI Probe users, please consider the following:

We recommend creating 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.

Once you’ve created the list, add it to the platform.

Step 1. Add the URLs that you would like to include in your OONI Run link for testing.

Note: You can copy and paste your list of URLs into the first URL slot, and each URL will populate each URL row (if copied based on the above text editor formatting).

Step 2. Click the Create Link button to create your OONI Run link.

You will now see your OONI Run link page which includes the title and description that you added, the expiration date of the link, as well as the list of URLs that you added for testing.

If you would like to edit your OONI Run link, click the Edit button in the top right corner.

Alternatively, click the Update Now button next to the link expiration date. Both actions will enable you to edit the data in your OONI Run link.

Once the OONI Run link is updated, it will be automatically updated for all users who have it installed in their OONI Probe application if they have “Install updates automatically” option enabled. Alternatively, they will be able to update the OONI Run link manually.

If you have old OONI Run v1 links (created through the use of the previous OONI Run platform) that you have embedded as widgets into your website or which you are sharing for testing, please update them to use OONI Run v2.

You can update old OONI Run v1 links through the following steps.

Step 1. Scroll down towards the end of the page to the “URLs” section.

Step 2. Click on “Do you have old OONI Run v1 links? Click here to add URLs from such links”.

You will now see a pop-up window for adding your old OONI Run v2 link.

Step 3. Add your old OONI Run v1 link in the “OONI Run Link” field.

Step 4. Click Add URLs.

Step 5. Click Create Link to create a new OONI Run v2 link based on the URLs of your old OONI Run v1 link.

Note: Through the data fields of the “Create OONI Run Link” page, you will also need to add a title, description, and expiration date for your new OONI Run v2 link before creating it.

To share your OONI Run link, click the copy icon next to your OONI Run link in the “Share this link” section. Then share the copied link with OONI Probe users who you would like to perform testing.

You can also share your link directly on Twitter/X by clicking on the “Tweet” button.

Community members often share OONI Run links on Twitter/X when they want to encourage more widespread testing.

Image: Tweet by Thai Netizen Network sharing an OONI Run link for the testing of Change.org in Thailand.

An OONI Run link can only be used with the OONI Probe mobile app.

OONI Run v2 is currently only supported on Android. We aim to release support for OONI Run v2 on OONI Probe iOS in subsequent versions.

Step 1. Please install the OONI Probe mobile app on Android. If you already have OONI Probe Android installed, please update to the latest version (4.0.0) for OONI Run v2 support.

Step 2. Tap on the OONI Run link that you received, and open it with your OONI Probe mobile app (not with a web browser). This will open a screen in your OONI Probe app, displaying information from the OONI Run link (as illustrated below).

As you can see from the above example, we have opened an OONI Run link for the testing of social media in our OONI Probe Android app. This shows information about the requested testing, as well as the list of websites that we are being asked to test.

The Test Settings of the OONI Run link include support for:

Step 3. To test the websites included in the OONI Run link, tap Install Link in the bottom right corner of the screen. This will install the OONI Run link in your OONI Probe mobile app, enabling you to change your OONI Run link settings and to uninstall the OONI Run link at any time.

Once installed, you can find your OONI Run link as a card in the Dashboard of your OONI Probe mobile app (listed under the “OONI Run Links” section).

Now that your OONI Run link has been installed (while being configured to run automatically), you don’t need to do anything else. Your OONI Probe app will automatically test the websites in the OONI Run link on an ongoing basis!

You can find the test results through the Test Results tab of your OONI Probe app.

By tapping on each of the tested websites displayed, you will find further information, including links to relevant OONI measurements that are published on OONI Explorer in real-time.

In the above example, we can see that TikTok was found accessible on the tested network. The “Data” button provides access to the raw OONI network measurement data, while the “Show in OONI Explorer” button provides a link to the published measurement. You can share the measurement through the use of the share button on the top right corner.

If at any moment you would like to change your OONI Run link settings, or uninstall the OONI Run link entirely, you can do so through the OONI Run link card installed in your OONI Probe mobile app.

Through your installed OONI Run link card, you can change the settings by:

If you would like to remove the OONI Run link card from your OONI Probe app, tap the “Uninstall Link” button.

In the event that you have disabled automated OONI Run link testing and would like to manually test websites included in your OONI Run link, you can do so by tapping the main “Run” button in the OONI Probe Dashboard, tapping the “Deselect all tests” button (to deselect all other OONI Probe tests), and by only enabling the OONI Run link test.

Finding your OONI Run v2 measurements on OONI Explorer

By default, all OONI Probe measurements from OONI Run v2 links are automatically published on OONI Explorer as open data in real-time. But given that OONI Explorer hosts a wealth of data – more than 2 billion measurements collected from 242 countries and territories since 2012 – finding the specific measurements from your OONI Run link was previously quite challenging.

We are excited to share that you can now easily find and aggregate measurements from your specific OONI Run v2 link through OONI Explorer! Specifically, you can filter measurements in both the OONI Explorer Search Tool and Measurement Aggregation Toolkit (MAT) based on the ID of your OONI Run v2 link (“OONI Run Link ID”).

The ID of your OONI Run link are the last digits displayed in the link. In the following example, the OONI Run link ID is 10015.

You can find measurements collected by all those who ran your OONI Run link through the following steps.

Step 1. Access the OONI Explorer Search Tool: https://explorer.ooni.org/search

Step 2. Add the last digits of your OONI Run link in the “OONI Run Link ID” field on the left. Below we have added 10015 based on the previous OONI Run link example.

Step 3. Click the Filter Results button.

You have now filtered OONI Explorer measurements to only view those collected based on your OONI Run v2 link.

Similarly, you can use the ID of your OONI Run link to aggregate measurements from your specific OONI Run v2 link through the OONI Explorer Measurement Aggregation Toolkit (MAT). By adding the ID digits in the “OONI Run Link ID” field of the MAT and clicking Show Chart, you will generate charts that are limited to the measurements collected through your OONI Run link.

Optional, but encouraged: Adding your websites to test lists

If some of the websites that you used for OONI Run links 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.