Admin

oTree’s admin interface lets you create, monitor, and export data from sessions.

Open your browser to the root url of your web application. If you’re developing locally, this will be http://127.0.0.1:8000/.

Password protection

When you first install oTree, The entire admin interface is accessible without a password. However, when you are ready to deploy to your audience, you should password protect the admin.

If you are launching an experiment and want visitors to only be able to play your app if you provided them with a start link, set the environment variable OTREE_AUTH_LEVEL to STUDY.

To put your site online in public demo mode where anybody can play a demo version of your game (but not access the full admin interface), set OTREE_AUTH_LEVEL to DEMO.

If you don’t want any password protection at all, leave this variable unset/blank.

Participant labels

Whether or not you’re using a room, you can append a participant_label parameter to each participant’s start URL to identify them, e.g. by name, ID number, or computer workstation. For example:

http://127.0.0.1:8000/room/my_room_name/?participant_label=John

oTree will record this participant label. It will be used to identify that participant in the oTree admin interface and the payments page, etc. You can also access it from your code as self.participant.label.

Arrival order

(Note: if using single-use links, this section does not apply.)

oTree will assign the first person who arrives to be P1, the second to be P2, etc.

Configure sessions

You can make your session configurable, so that you can adjust the game’s parameters in the admin interface, without needing to edit the source code:

_images/edit-config.png

For example, let’s say you are making a public goods game, whose payoff function depends on an “efficiency factor” parameter that is a numeric constant, like 1.5 or 2. The usual approach would be to define it in Constants, e.g. Constants.multiplier

However, to make your custom parameter configurable, instead of adding it to Constants, add it to your config in SESSION_CONFIGS. For example:

{
    'name': 'my_session_config',
    'display_name': 'My Session Config',
    'num_demo_participants': 2,
    'app_sequence': ['my_app_1', 'my_app_2'],
    'multiplier': 1.5,
},

Then, when you create a session in the admin interface and select this session config, the multiplier parameter will be listed, and you can change it to a number other than 1.5. If you want to explain the meaning of the variable to the person creating the session, you can add a 'doc' parameter to the session config dict, e.g.:

{
    'name': 'my_session_config',
    'display_name': 'My Session Config',
    'num_demo_participants': 2,
    'app_sequence': ['my_app_1', 'my_app_2'],
    'multiplier': 1.5,
    'doc': """
    Edit the 'multiplier' parameter to change the factor by which
    contributions to the group are multiplied.
    """
},

Then in your app’s code, you can do self.session.config['multiplier'] to retrieve the current session’s efficiency factor.

Notes:

  • For a field to be configurable, its value must be a simple data type (number, boolean, or string).
  • On the “Demo” section of the admin, sessions are not configurable. It’s only available when creating a session in “Sessions” or “Rooms”.

Also see Choosing which treatment to play.

Customizing the admin interface (admin reports)

You can add a custom tab to a session’s admin page with any content you want; for example:

  • A chart/graph with the game’s results
  • A custom payments page that is different from oTree’s built-in one

Here is a screenshot:

_images/admin-report.png

To use this feature, you create a template called AdminReport.html, and optionally, a method Subsession.vars_for_admin_report.

Here is a trivial example, where we add an admin report that displays a sorted list of payoffs for a given round.

First, define a method vars_for_admin_report on the Subsession. This works the same way as vars_for_template(). For example:

class Subsession(BaseSubsession):
    def vars_for_admin_report(self):
        payoffs = sorted([p.payoff for p in self.get_players()])
        return {'payoffs': payoffs}

Then create a template AdminReport.html in the same folder as the app’s regular templates, and display whatever variables were passed in vars_for_admin_report:

<p>Here is the sorted list of payoffs in round {{ subsession.round_number }}</p>

<ul>
    {% for payoff in payoffs %}
        <li>{{ payoff }}</li>
    {% endfor %}
</ul>

Notes:

  • subsession, session, and Constants are passed to the template automatically.
  • AdminReport.html does not need to use {% block %} or {% extends %} etc. The above example is valid as the full contents of AdminReport.html.

If one or more apps in your session have an AdminReport.html, your admin page will have a “Reports” tab. Use the menu to select the app and the round number, to see the report for that subsession.

Tip: if you are displaying the same chart in the admin report and participant pages, you can do something like this:

class Results(Page):

    def vars_for_template(self):
        return self.subsession.vars_for_admin_report()

Likewise, you can reuse AdminReport.html in the participant template with an {% include %}.

If you’re generating a chart with JavaScript, remember to use the |json filter.

Kiosk Mode

You can enable “kiosk mode”, a setting available in most web browsers, to prevent participants from accessing the browser’s address bar, hitting the “back” button, closing the browser window, etc. Here are instructions for different browsers.

iOS (iPhone/iPad)

  1. Go to Setting – Accessibility – Guided Access
  2. Turn on Guided Access and set a passcode for your Kiosk mode
  3. Open your web browser and enter your URL
  4. Triple-click home button to initiate Kiosk mode
  5. Circle areas on the screen to disable (e.g. URL bar) and activate

Android

There are several apps for using Kiosk mode on Android, for instance: Kiosk Browser Lockdown.

_images/android.png

Chrome on PC

  1. Go to Setting – Users – Add new user
  2. Create a new user with a desktop shortcut
  3. Right-click the shortcut and select “Properties”
  4. In the “Target” filed, add to the end either --kiosk "http://www.your-otree-server.com" or --chrome-frame  --kiosk "http://www.your-otree-server.com"
  5. Disable hotkeys (see here)
  6. Open the shortcut to activate Kiosk mode

IE on PC

IE on PC See here

Mac

There are several apps for using Kiosk mode on Mac, for instance: eCrisper. Mac keyboard shortcuts should be disabled.

Monitor sessions

The admin interface lets you monitor the live progress of your sessions.

Payments page

At the end of your session, you can open and print a page that lists all the participants and how much they should be paid.

Export Data

In the admin interface, click on “Data” (try http://127.0.0.1:8000/export/) to download your data as CSV or Excel.

Autogenerated documentation

If you add a doc= argument to your model fields like this:

class Player(BasePlayer):
    contribution = models.IntegerField(doc="how much this player contributed")

It will be included in a “documentation” file that is available on the “Data Export” page.

Debug Info

When oTree runs in DEBUG mode (i.e. when the environment variable OTREE_PRODUCTION is not set), debug information is displayed on the bottom of all screens.