Analytics#

Openverse uses Plausible for analytics. This document describes how to set up and use the Openverse Plausible integration. It is not necessary to set up Plausible for general frontend development unless specifically working on custom events.

Running Plausible locally requires Docker and docker-compose.

Plausible set up and first run#

Use the following just recipes to set Plausible up locally:

# Runs the portion of the docker-compose stack that includes Plausible
just frontend/up

# Sets up Plausible with a default user and the localhost testing site
# Only necessary the first time you run Plausible locally, when adding
# new custom events, or any time after you run `just down -v`
just frontend/init

If you have already run just up and just init at the root of the repository, then Plausible is already set up and running the commands above is not necessary.

Note

just frontend/up may take some time on first run as it will need to download various docker images required for the Plausible stack.

Access Plausible#

Plausible is accessible at http://0.0.0.0:50288. The default localhost username and password are:

  • Username: deploy@example.com

  • Password: deploy

Our setup script will have already added the “localhost” site used for testing the Plausible integration on a locally running Openverse frontend. Refer to the frontend quickstart documentation for instructions to set up the Openverse frontend locally.

Custom events#

Plausible supports custom events via its “goals” feature. Plausible’s documentation for this feature can be found here.

Sending custom events to Plausible is done by calling the sendCustomEvents function. For this function to accept a custom event name, you must update the Events type in frontend/src/types/analyticts.ts to include the new event name and any payload elements unique to the event.

Custom events must be added to Plausible for it to record them. You may do this one of two ways:

  • Automatically:

    1. Run just frontend/init, which automatically extracts the events name from the Events type

  • Manually:

    1. Visit http://0.0.0.0:50288/localhost/settings/goals and click the “+ Add goal” button

    2. Select the “custom event” trigger and add the custom event name in the text box

    3. Click “add goal” to save the new custom event

If you are testing custom events added by others, you must also follow this process for them to appear in your local environment. just frontend/init will be the simplest way to do so in those cases, provided the change request includes the necessary changes to the Events type.

After adding the custom event, upon receiving at least one instance of the event, Plausible will display the event under the “Goal Conversions” section on the stats page. It will look like this:

Plausible "Goal Conversions" example at bottom of site stats page

If you are adding a new custom event that includes unique payload elements, you can click the custom event name in the “Goal Conversions” section to reveal the payload elements and confirm that your payload items appear as expected.

Sending#

To send a custom event from the frontend, use the sendCustomEvents function generated by the useAnalytics composable. For example:

import { useAnalytics } from "~/composables/use-analytics"

const { sendCustomEvent } = useAnalytics()
const handleClick = () => {
  sendCustomEvent("COOL_EVENT_NAME", {
    mediaType: props.mediaType,
  })
}

You must set up the custom event following the instructions in the previous section before this will do anything.

Default payload#

sendCustomEvent will automatically include the following payload elements:

  • width: The width of the screen in pixels at the time of the event

  • height: The height of the screen in pixels at the time of the event

  • breakpoint: One of the Openverse breakpoint values, for determining broad page layout for a given event

While these are included by default, any of them may not be present for a given event instance if the information was not available at the time. For example, referrer is not available if the page is visited directly.

Payload props unique to individual events may not use the same name as any of the props listed above or they will overwrite the default props.