Release Notes

Version 1.0.7 (2025-06-05)

Improvements

• Enhanced /players/list endpoint with additional player information:

  • Added pitch_time field to show the player's pitch time configuration

  • Added duration field to display the associated video's duration

  • Maintains backward compatibility with existing implementations

Example Response

[
  {
    "id": "player1",
    "name": "My Player",
    "pitch_time": 0,
    "duration": 3600,
    "created_at": "2025-06-05T10:00:00Z"
  }
]

---

Version 1.0.6 (2025-05-30)

New Features

• Added new /custom_metrics/{player_id}/list endpoint that provides a list of all custom metrics for a specific player:

  • Returns custom metric information including ID, name, time, and sequential number

  • Allows tracking specific video time points for retention analysis

  • Enables calculation of user engagement percentages at specific video timestamps

Example Response

[
  {
    "id": "metric1",
    "name": "First Key Point",
    "time": 30,
    "sequential_number": 1
  },
  {
    "id": "metric2",
    "name": "Second Key Point",
    "time": 60,
    "sequential_number": 2
  }
]

Understanding Custom Metrics and User Engagement

The custom metrics endpoint works in conjunction with the /times/user_engagement endpoint to help calculate retention rates at specific video timestamps. Here's how to use them together:

1. First, list your custom metrics for important video timestamps using the /custom_metrics/{player_id}/list endpoint

2. Then, use the /times/user_engagement endpoint to get the number of users at each timestamp by providing:

   • player_id: The ID of your player

   • video_duration: Total duration of the video in seconds

   • start_date and end_date: The period you want to analyze

   • timezone: Your preferred timezone for date filtering

Example request to /times/user_engagement:

{
  "start_date": "2023-10-26 18:24:05",
  "end_date": "2023-11-26 18:24:05",
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "video_duration": 3600,
  "timezone": "America/Sao_Paulo"
}

1. The user engagement endpoint will return data showing how many users reached each second of the video

2. You can then calculate retention by comparing the number of users at each custom metric timestamp against the total number of users

For example, if you have:

• Total users: 100

• Users at 30 seconds (First Key Point): 80

• Users at 60 seconds (Second Key Point): 50

The retention rates would be:

• First Key Point: 80% (80/100)

• Second Key Point: 50% (50/100)

This combination allows you to:

• Track user engagement at specific, meaningful points in your video

• Calculate retention rates for custom-defined milestones

• Analyze how many users are reaching your key video moments

• Make data-driven decisions about video content and length

---

Version 1.0.5 (2025-05-28)

New Features

• Added new /players/list endpoint that provides a list of all players belonging to the authenticated user's company:

  • Returns basic player information including ID, name, and creation date

  • Automatically filters players based on the authenticated user's company

  • Supports JSON response format

Example Response

[
  {
    "id": "player1",
    "name": "My Player",
    "created_at": "2025-05-28T10:00:00Z"
  }
]

---

Version 1.0.4 (2025-05-27)

New Features

• Added new /events/leaderboard endpoint that provides player rankings based on video engagement metrics:

  • Supports multiple leaderboards with different player limits in a single request

  • Allows filtering by event types (started, finished, viewed, clicked, paused)

  • Includes metrics for total plays, unique plays by session, and unique plays by device

  • Supports date range filtering with optional end date

Example Request

{
  "company_id": "2b884cba-0b12-42ce-b3a1-7a3182d414df",
  "leaderboards": [
    {
      "leaderboard_limit": 10,
      "start_date": "2023-10-26",
      "end_date": "2023-11-26",
      "event": "finished"
    },
    {
      "leaderboard_limit": 5,
      "start_date": "2023-09-26",
      "event": "started"
    }
  ],
  "timezone": "America/Sao_Paulo"
}

Example Response

[
  {
    "leaderboard_name": "leaderboard_10",
    "event": "finished",
    "leaderboards": [
      {
        "player_id": "player1",
        "total_plays": 100,
        "uniq_plays": 50,
        "uniq_device_plays": 25
      }
    ]
  }
]

---

Version 1.0.3 (2025-05-15)

Improvements

• Improved performance on the following endpoints:

  • /events/total_by_company_day

Detailed explanation

Sometimes when performing a request against the endpoint users were reaching out of resource without the request actually being that heavy, this was due to the way the endpoint was aggregating data, requests should be normalized and use the proper amount of resource.

---

Version 1.0.2 (2025-05-15)

Improvements

• Enhanced error handling for exceptions when the request is using more resources than it's allowed based on the company plan:

  • Added explicit handling for AUTHENTICATION_FAILED

  • Added explicit handling for MEMORY_LIMIT_EXCEEDED

Examples of the Error Responses for 401 - Non Authorized

When a company doesn't have access to the API:

{
  "error": "This company does not have access to the public analytics API.",
  "code": 516
}

When a query exceeds the resource limits for the company plan tier:

{
  "error": "Your api key tier is not enough to perform this query. Please contact support at [e-mail]",
  "code": 241
}

---

Version 1.0.1 (2025-05-15)

Bug Fixes

• Fixed timezone handling in the /sessions/stats_by_field_by_day endpoint to ensure consistent date reporting across different timezones. This affects how dates are calculated in the following metrics:

  • Session statistics by day

  • Conversion rates

  • Event timestamps

  • Date-based aggregations

Example of the Fix

Before this fix, when using timezone "America/Sao_Paulo" (GMT-3), events that occurred on the same day could be split across two different dates due to timezone conversion issues. For example:

// Before the fix
{
    "grouped_field": "United States",
    "total_viewed": 100,
    "date_key": "2025-05-13"  // Some events from May 14 were incorrectly grouped here
},
{
    "grouped_field": "United States",
    "total_viewed": 200,
    "date_key": "2025-05-14"  // Only some events from May 14 were here
}

Now, all events from the same day are properly grouped together, regardless of the timezone specified in the request:

// After the fix
{
  "grouped_field": "United States",
  "total_viewed": 300, // All events from May 14 are now correctly grouped
  "date_key": "2025-05-14"
}

---

Note: This version includes fixes and improvements to existing functionality without introducing new features or breaking changes.