Adding Google Analytics to Your Visual Novel link

“Analysis without numbers is only an opinion.” - Dave Akin

Traditionally, a visual novel is released, and that’s it. Unless a player gives a review, there’s little feedback as to what happens after that. The creator might be interested in knowing how many players play the game, how many make it through the game, and how many make it to an ending, but it’s been difficult to get feedback on these topics.

While Ren’Py has always been able to make web requests, creating your own web service with the ability to analyze the requests is a fairly daunting proposition. Thankfully, you don’t have to do that. The Google Analytics service is now capable of reporting on events that occur inside applications, including visual novels. This makes it possible to use that framework to report on and analyze what happens in your game.

This article will show you how to add Google Analytics to your Ren’Py visual novel. Of course, some users won’t want to be tracked, so the framework is controlled by a preference that the user is prompted for. With this information, a game creator can understand how players play the game. This might be useful to discover unreachable paths, create fan material, and of course, answer the eternal question: Who is best girl?

Setting Up Your Google Analytics Account link

To get started with Google Analytics, you’re going to want to get a Google account, and then visit:

https://analytics.google.com/analytics/web/?authuser=0#/provision/SignUp

This is going to bring you to a page where you can create a new Analytics account. I’ve set the Ren’Py framework up to track things as if the game was a website, so you’ll want to set it up as a website. You’ll have to enter a fake URL, but that shouldn’t be a big deal. Here’s how I set up my account:

Once that’s done, it’ll bring you to a page that gives you your tracking ID:

The tracking ID begins with UA. You’ll need to save it to make sure your events are routed to the right place.

Adding Analytics to Your Game link

There’s two changes you’ll need to add the analytics support for Ren’Py itself. The first is to download the analytics script file from:

https://patreon.renpy.org/_static/analytics.rpy

And place it into your project’s game directory. Then you’ll have to add the tracking ID, using a line like:

define analytics.tracking_id = "UA-123456789-1"

This line can go anywhere, but probably makes most sense at the end of options.rpy.

Asking the Player for Permission link

Tracking a player without asking for permission is bad form, and might also be against privacy laws in certain countries, like those that comprise the European Union. (I am not a lawyer, so please do your own research as to what tracking is acceptable.) As a result, before a player can be tracked, the player must consent.

That’s done by setting the persistent.analytics variable to true. This can be done by a screen or a menu. Here’s what I used in my example game.

label start:

    if persistent.analytics is None:

        menu:
            "Welcome! This game supports analytics. Enabling it will help us make better games, and will send data to Google Analytics and the developers. Do you want to enable analytics?"

            "Yes.":
                $ persistent.analytics = True
                "Thank you."

            "No.":
                $ persistent.analytics = False
                "No problem!"

The first time a user starts the game, persistent.analytics will be None. This will then cause this menu to display and prompt the user. Once they make their pick, it will be remembered and they will not be prompted again.

It probably makes sense to also have a preference that lets the player change their decision. This can be done with a custom preference. You can see that article for a discussion of where and how to add it, but the screen language looks like:

vbox:
    style_prefix "radio"
    label _("Tracking")
    textbutton _("Enabled") action SetField(persistent, "analytics", True)
    textbutton _("Disabled") action SetField(persistent, "analytics", False)

Creating Events link

Finally, events can be sent to Google Analytics by calling the analytics.event function:

$ analytics.event("Ending", "1. Nothing to Say")

This will check to see if the player has enabled analytics. If they have, at the start of the next interaction, Ren’Py will start a background thread that pushes the event to the Google Analytics server.

There are two arguments that analytics.event requires. The first is a category of event, and the second is an action that the event performs. While these are basically freeform, they can be used in Google Analytics to filter the event.

We might have a line like the above for each ending, with the “Ending” category and a name for each ending. It’s also possible to have other categories - for example, it might be reasonable to have a “Chapter” category, and place a line like:

$ analytics.event("Chapter", "Chapter 4")

before each chapter.

Automatic Label Events link

While it probably makes sense to add events for important things like game starts and ends by hand, doing so throughout the script could be a chore. Adding the following block of script will cause Ren’Py to automatically log a label event each time a label is reached:

init python:

    def label_callback(label, abnormal):

        # Filter out labels that are part of Ren'Py and not the game.
        filename = renpy.get_filename_line()[0]
        if filename.startswith("renpy/common/"):
            return

        analytics.event("Label", label)

    config.label_callback = label_callback

Viewing the Data link

Once you have your script set up, you can play through, and see the data in Google Analytics. If you go to the “Realtime” tab, and the “Events” section, you’ll see the events within seconds after they happen.

For real analysis, you’ll want to go down to “Behavior” and “Events”. That will let you go back through history, and drill down into the events to see which occurred when. This data can be delayed, however - it may take up to a day for it to start showing up.