Skip to content

0055: Temporarily Expose Player Clicks and Player Conversions in Player API

STATUS

Accepted

CONTEXT

During the PlayerAPI MVP adoption process, it was identified that the ad-tracking consuming systems (AdGem API and ServiceHub) need access to additional records that were not contemplated in the initial MVP scope: - Player Clicks: Records of clicks associated with specific players, containing the necessary information to build postbacks. - Player Conversions: Complete conversion records, including player geo, publisher info (c1 to c5), reward information, and others. Mainly used to build postbacks and verify player interactions.

These legacy ad-tracking issues were previously identified, and the contemplated solution was adding Player Sessions to reduce the need to share the click/conversion event data across different places, but the Player API development was prioritized over the ad-tracking 3.0 version, which included these improvements.

The event data from those records is critical for existing systems to complete the migration from ad-tracking to PlayerAPI. However, exposing these records contradicts the long-term vision of PlayerAPI, which seeks to focus solely on player transactional data and not on tracking events.

Considered Options

Option 1: Temporarily expose records in PlayerAPI v1 and remove them in v2 - Add endpoints for player clicks and player conversions in the current version of PlayerAPI. Marking these endpoints as deprecated from the start. - Consume those endpoints as a replacement on the dependent systems. - Complete the migration. - Release Player Sessions endpoints - Replace these temporal endpoints with Player Sessions endpoints on dependent systems. - Monitor Player Sessions adoption and temporal endpoints deprecation until zero usage. - Remove deprecated endpoints.

Option 2: Update ad-tracking to provide a solution aligned with PlayerAPI's purpose and then migrate to PlayerAPI - Delay the deprecation of ad-tracking. - Create a new version of ad-tracking that removes clicks and conversions in favor of player sessions - Update consuming services to use Player Sessions - Update PlayerAPI to expose Player sessions - Migrate to PlayerAPI-dependent systems

DECISION

Option 1: Temporarily expose player clicks and player conversions records in PlayerAPI v1, with an explicit commitment to remove them in version 2.

Rationale:

  1. Migration velocity: Allows deprecating ad-tracking immediately without blocking consumer systems' adoption.

  2. Technical pragmatism: Avoids creating additional temporary infrastructure that would also need to be deprecated.

  3. Operational simplicity: Maintains a single access point for player data during the transition.

  4. Cost-benefit: Minimizes development effort by reusing existing PlayerAPI infrastructure.

Implementation:

  • New endpoints will be marked as @deprecated in OpenAPI documentation.
  • HTTP headers will include: Warning: 299 - "This endpoint is deprecated and will be removed in v2".
  • Planned removal date will be documented (version 2.0). Player API V2 is expected to ready by end of 2026 Q2.
  • Documentation on alternative migration paths will be provided.

CONSEQUENCES

Positive

  • Immediate unblocking: Migration from ad-tracking can continue without waiting for additional developments.
  • Technical debt reduction: ad-tracking can be deprecated according to the planned schedule.

Negative

  • Temporarily inflated scope: PlayerAPI v1 includes functionality not aligned with its long-term purpose.
  • Permanent adoption risk.
  • Temporary technical debt.

Risks

  • Pressure to maintain endpoints: Business might pressure to keep endpoints beyond v2
  • Mitigation: Clear alternatives documented before v2 release, executive commitment to the vision.

NOTES

References

Original Author

Quintin S.

Approval date

[Date]

Approved by

[Pending]

Appendix

Temporary Endpoints to Implement

GET /v1/clicks/{clickId}
GET /v1/players/{adgemUid}/clicks
GET /v1/conversions/{conversionId}
GET /v1/players/{adgemUid}/conversions