Skip to content

0029: Player API POC Phase

STATUS

Draft

CONTEXT

The AdGem system currently manages player progress through an internal PHP package (ad-tracking) that has accumulated significant technical debt. This package handles tracking of player progress through offers, and will eventually also handle validation of incoming postbacks (such as enforcement of Max Completion Time and Conditional Goals) and management of player data (targeting info - demographics, affinities for certain campaign verticals, etc). As the system has evolved, this package has become increasingly difficult to maintain and extend.

Additionally, there is a growing external requirement to provide publishers with player progress data. This will allow publishers to rely on AdGem for tracking of player progress (as a complementary feature of the Targeted API) and will enable them to perform traffic optimizations and targeting changes on a campaign-by-campaign basis.

The current approach of continuing to add functionality to the ad-tracking package would exacerbate existing technical debt and make future changes more risky and difficult to implement.

Considered Options

  1. Continue using the existing PHP package - Add new functionality to the existing ad-tracking package
  2. Create a new internal REST API - Build a new Player API service to replace the PHP package functionality
  3. Create an external-facing API - Build an API that publishers can directly consume
  4. Hybrid approach - Create an internal API that serves both internal services and external publishers through a gateway

DECISION

We will create a new internal REST API called the Player API to replace the functionality currently provided by the ad-tracking PHP package. This API will be internal-only, with external access provided through the existing Targeted API.

The POC phase will focus on implementing the Create Player endpoint to validate the infrastructure and approach before proceeding to the full MVP phase.

Architecture Overview

flowchart TB subgraph external [External Publishers] pub[Publisher] end subgraph adgem [AdGem Services] targeted_api[Targeted API] adgem_api[AdGem API] player_api[Player API] end subgraph data [Data Layer] db[(Dynamo)] end pub --> targeted_api targeted_api --> player_api adgem_api --> player_api player_api --> db

Data Flow for POC

sequenceDiagram participant TA as Client participant PA as Player API participant DB as Database TA->>PA: POST /v1/apps/{app_id}/players Note over PA: Create Player endpoint PA->>DB: Insert player record DB-->>PA: Success response PA-->>TA: Player created confirmation

POC Scope

The POC phase will implement:

  1. Infrastructure Setup
  2. Setup of Laravel app with /healthcheck endpoint
  3. Authentication and authorization mechanisms (likely using AWS Cognito)
  4. Logging and monitoring in DataDog

  5. Github CI/CD

    • automated tests
    • semantic release
    • deployment

  6. Create Player Endpoint

  7. POST /v1/apps/{app_id}/players endpoint
  8. Player record creation and validation
  9. Basic error handling and response formatting

API Design

Create Player Endpoint

POST /v1/apps/{app_id}/players
Content-Type: application/json

{
  "publisher_id": "integer",
  "app_id": "integer",
  "adgem_uid": "string",
  "external_player_id": "?string"
}

In the future we may want to include the following fields, but they aren't necessary at this point.

  "platform": "string",
  "device_info": {
    "device_id": "string",
    "os_version": "string",
    "device_name": "string"
  },
  "metadata": {
    "country": "string",
    "timezone": "string",
    "ip_address": "string"
  }

Response:

{
  "player_id": "string",
  "created_at": "timestamp"
  // may include more in the future. The createPlayer method in ad-tracking returns a Player object, which has a lot of fields on it. When we begin implementation, we'll need to go through all the existing uses of the createPlayer method to see what data needs to be included in the API Response for this endpoint
}

CONSEQUENCES

Positive Outcomes

  • Reduced Technical Debt: Moving away from the legacy PHP package will improve maintainability and reduce risk
  • Better Versioning: API versioning will enable easier future support and backward compatibility
  • Improved Testing: REST API endpoints are easier to test and mock than PHP package functions
  • Scalability: API-based architecture provides better scaling (horizontal and vertical) capabilities
  • Clear Separation of Concerns: Internal vs external API boundaries will be clearly defined

Negative Outcomes

  • Migration Complexity: Existing services (mainly the adgem api) will need to be updated to use the new Player API rather than relying on the php package
  • Additional Infrastructure: New API service requires additional infrastructure and monitoring
  • Learning Curve: Team will need to adapt to new API patterns and practices

Risks

  • Performance: Adding an extra network call will increase overall latency.

NOTES

References

Original Author

Dylan Kreth

Approval date

[To be filled]

Approved by

[To be filled]

Appendix

Future MVP Phase Scope

The MVP phase will expand the Player API to expose all existing functionality of the ad-tracking php package as REST endpoints (deprecating methods that are no longer needed)

Integration Points

The Player API will integrate with:

  1. Targeted API: For serving player progress data to external publishers
  2. AdGem API: For tracking of player progress and postback validation
  3. Data Warehouse: For analytics and reporting