Ravensight

Connect a BI tool

There are two ways to put Ravensight numbers in a reporting tool. Both work today, and the guides below give the steps for Looker Studio, Tableau, Power BI and Metabase.

  • Your own warehouse, fed by bucket export. Bucket export writes every event to your own S3 bucket as Parquet or gzip JSON lines, in folders named game_id=, dt= and hour=. You load or attach those files in a database or warehouse you run, then point the BI tool at it with that tool's own connector. This is the route for event-level reporting and large volumes. Each exported event counts as five events on your shared event meter.
  • The REST data API. Read game data over REST answers the same metrics the dashboard shows (metrics, retention, funnel, monetization and more) as JSON, for a window of at most 31 days per request. This is the route for small summary tables. Every request that reads a game costs one programmatic call, 100,000 events on the shared event meter, about $0.05 once the included allowance is spent, so a report that refreshes often adds up: each refresh of each table is one request.

The token. The REST API takes a studio-bound MCP token from Settings > MCP access, sent only in the Authorization header as Bearer gt_mcp_.... A token in the URL is refused. For a reporting tool, mint a token for this purpose only, limit it to the tools the report reads and to the projects it needs, and set a monthly spending cap on it. The studio must have funded a prepaid balance once. Anyone who can open the report's data source settings can see the token, so treat the report file like the token.

Money in the REST answers is whole minor units of one currency (revenue: 1999 with minorUnitDigits: 2 is 19.99). Divide by 10 to the power of minorUnitDigits to display it, and never add two currencies together.

Looker Studio

From your own warehouse

  1. Set up bucket export to your S3 bucket, in Parquet if your warehouse reads it.
  2. Load the exported files into a database Looker Studio has a connector for, such as PostgreSQL, MySQL or a Google Cloud warehouse, on a schedule that suits you. The hourly _ravensight_manifest.json lists each new file and its row count.
  3. In Looker Studio, choose Create, then Data source, and pick the connector for that database.
  4. Enter the database's connection details and choose the table that holds the events.
  5. Build the report on its columns: event, tsIso, platform, gameVersion and the rest of the row schema.

From the REST data API, through a Google Sheet

Looker Studio has no built-in connector that sends an Authorization header to an arbitrary API, so this route writes the answer into a Google Sheet that Looker Studio then reads.

  1. Create a Google Sheet and open Extensions, Apps Script.
  2. In the script's Project settings, add a script property named RAVENSIGHT_TOKEN holding your token, so the token is not in the code.
  3. Paste the script below, replace GAME_ID, and run loadRevenue once to grant it access.
  4. Add a time-driven trigger for loadRevenue (once a day is one request a day).
  5. In Looker Studio, add the Google Sheets connector and choose this sheet.
function loadRevenue() {
  const token = PropertiesService.getScriptProperties().getProperty('RAVENSIGHT_TOKEN');
  const response = UrlFetchApp.fetch('https://api.ravensight.io/api/v1/data/games/GAME_ID/monetization', {
    headers: { Authorization: 'Bearer ' + token }
  });
  const body = JSON.parse(response.getContentText());
  const rows = [['date', 'currency', 'revenue_minor_units', 'minor_unit_digits']];
  body.byCurrency.forEach(function (currency) {
    currency.series.forEach(function (day) {
      rows.push([day.date, currency.currency, day.revenue, currency.minorUnitDigits]);
    });
  });
  const sheet = SpreadsheetApp.getActive().getSheets()[0];
  sheet.clearContents();
  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
}

Tableau

From your own warehouse

  1. Set up bucket export and load or attach the files in a database or warehouse Tableau has a connector for.
  2. In Tableau, under Connect, choose To a Server and pick that database's connector.
  3. Sign in with the database's own credentials and drag the events table onto the canvas.
  4. Use tsIso as the date field and event, platform and gameVersion as dimensions.

From the REST data API, through a saved file

Tableau reads JSON files, so a scheduled command saves the answer and Tableau connects to the file.

  1. Put your token in an environment variable named RAVENSIGHT_TOKEN on the machine that runs the command.
  2. Run the command below, replacing GAME_ID, and schedule it with your system's scheduler.
  3. In Tableau, under Connect, choose To a File, JSON file, and open retention.json.
  4. Select the cohorts schema level to get one row per first-seen cohort with its d1 and d7.
  5. Refresh the extract after each scheduled run.
curl -sf https://api.ravensight.io/api/v1/data/games/GAME_ID/retention \
  -H "Authorization: Bearer $RAVENSIGHT_TOKEN" -o retention.json

Power BI

From your own warehouse

  1. Set up bucket export and load or attach the files in a database or warehouse Power BI has a connector for.
  2. In Power BI Desktop, choose Get data and pick that database's connector.
  3. Enter the server and database, sign in with the database's own credentials, and select the events table.
  4. Choose Load, or Transform data to shape it first.

From the REST data API

The Web connector in Power BI Desktop can send the Authorization header itself.

  1. Choose Get data, Web, then Advanced.
  2. In the URL parts, enter https://api.ravensight.io/api/v1/data/games/GAME_ID/metrics with your game id.
  3. Under the HTTP request header parameters, add Authorization with the value Bearer gt_mcp_....
  4. When asked how to connect, choose Anonymous: the header carries the token.
  5. In Power Query, expand the record into columns and choose Close & Apply. Each refresh is one request per query.

Metabase

Metabase reads databases, not web APIs, so both routes end in a database.

From your own warehouse

  1. Set up bucket export and load or attach the files in a database Metabase supports, such as PostgreSQL or MySQL.
  2. In Metabase, open Admin settings, Databases, and choose Add database.
  3. Pick the database type, enter its connection details and save. Metabase scans the tables.
  4. Start a new question on the events table, or write SQL against it in the native query editor.

From the REST data API

  1. Create a table in a database Metabase already reads, for example ravensight_metrics(read_at, players, sessions, new_players, returning_players).
  2. Write a scheduled job that calls GET /api/v1/data/games/GAME_ID/metrics with the Authorization: Bearer header and inserts one row per run.
  3. Add that database in Metabase as above, if it is not there yet, and build questions on the table.