Skip to content

0065: [Replace app-groups with offer-placements]

STATUS

[Deferred]

CONTEXT

Currently, we offer some publishers the ability to use app-groups allowing them to create a new application(s) via AdGem dashboard to have a different set of offer placement (display our offers in a different part of their app), offer targeting (display a set of offers distinct in type or target player), language (I.E. Shopback multilang app), or integration type. This approach creates several significant problems:

  1. Tracking Issues: An AdGem UID does not have a one-to-one relationship with the player-app combination, resulting in multiple AdTracking Players with different AdGem UIDs. One for each application in the app-group.
  2. AdGem Database Malpractice: Since the app-groups are not represented on the Database schema, we're breaking the 2NF. See Reference.
  3. Complex Reward Management: Working with player rewards and transactions with app-groups is brittle because the system must depend on external factors like Player ID (externalPlayerId) instead of a single unified identifier managed by AdGem.
  4. Inefficient Requests: Multiple AdTracking Players per application lead to redundant API calls and complicated tracking logic.
  5. Manual Feature Management: As of now, the publisher doesn't have either access or awareness of the app-groups functionality, which is manually activated by an AdGem Admin.

The system needs a more streamlined approach that maintains a one-to-one relationship between a player and their identity within an application, while still allowing flexibility in displaying offers with different currencies, multipliers, languages, and campaign types.

Current Architecture (App-Groups)

graph TB subgraph "Publisher App" Player["Player<br/>(externalPlayerId)"] end subgraph "AdGem - Current App-Groups Structure" App1["Application 1<br/>USD Currency"] App2["Application 2<br/>EUR Currency"] App3["Application 3<br/>Spanish Language"] App4["Application 4<br/>Different Placement"] UID1["AdGem UID 1"] UID2["AdGem UID 2"] UID3["AdGem UID 3"] UID4["AdGem UID 4"] OW1["Offerwall 1"] OW2["Offerwall 2"] OW3["Offerwall 3"] OW4["Offerwall 4"] end subgraph "AdTracking Players" ATP1["Player Record 1"] ATP2["Player Record 2"] ATP3["Player Record 3"] ATP4["Player Record 4"] RW1["Reward 1"] RW2["Reward 2"] RW3["Reward 3"] RW4["Reward 4"] ATP1 --> RW1 ATP2 --> RW2 ATP3 --> RW3 ATP4 --> RW4 end Player -->|"Creates"| UID1 Player -->|"Creates"| UID2 Player -->|"Creates"| UID3 Player -->|"Creates"| UID4 UID1 --> App1 UID2 --> App2 UID3 --> App3 UID4 --> App4 App1 -."1:1".-> OW1 App2 -."1:1".-> OW2 App3 -."1:1".-> OW3 App4 -."1:1".-> OW4 UID1 --> ATP1 UID2 --> ATP2 UID3 --> ATP3 UID4 --> ATP4 style Player fill:#ff6b6b style UID1 fill:#ffd93d style UID2 fill:#ffd93d style UID3 fill:#ffd93d style UID4 fill:#ffd93d style ATP1 fill:#95e1d3 style ATP2 fill:#95e1d3 style ATP3 fill:#95e1d3 style ATP4 fill:#95e1d3

Problems Illustrated: - One player creates multiple AdGem UIDs (4 different identities) - Each configuration change requires a new application - Database shows 4 separate player records for the same person - No schema representation of the app-groups relationship - Complex reward tracking across multiple UIDs

Considered Options

Option 1: Continue with Current App-Groups Model - Maintain the existing structure where each configuration variation requires a new application. - Implement workarounds to handle the multiple AdGem UID per player issue. - Pros: No migration effort required, familiar to current admins and publishers. - Cons: Continues to create tracking problems, database complications, legacy support for new services, and inefficient usage.

Option 2: Introduce Offer Placements as Children of Applications - Create a new "placements" concept that functions as a child of applications - Each application contains multiple placements that handle currency, multiplier, integration type, offer limit, targeting, and logo configurations. - Players maintain a single ID per application and can navigate between different placements seamlessly. - Move offerwall fields to the application level, with placement-specific configurations handled by placements. - Deprecate the offerwall-app 1:1 concept and adopt the new 1:n app-placements. - Pros: Simplifies tracking, reduces database complexity, enables one-to-one player-to-app relationship, and encourages publishers to display more AdGem offers in their apps with less friction. - Cons: Requires significant architectural changes and migration effort.

Option 3: Enhance App-Groups with Virtual Grouping - Create a virtual grouping layer that links multiple applications together. - Maintain separate applications but add metadata to associate them as variants of the same base app. - Pros: Less disruptive to the current structure. - Cons: Does not fundamentally solve the tracking and ID proliferation issues, adds complexity without addressing root causes.

DECISION

Option 2: Implement Offer Placements as Children of Applications

We will replace the multiple application creation pattern with a placement-based architecture where:

  1. Application Structure: Applications will serve as the parent entity containing multiple placements at the publisher's convenience.
  2. Placement Functionality: Placements will replace the offerwall functionality by managing:
  3. Currency configuration.
  4. Multiplier settings.
  5. Integration type.
  6. Targeted offers.
  7. White labeling.
  8. Language preferences.
  9. Field Migration: Offerwall fields will be moved to the application level where appropriate, with placement-specific configurations handled by individual placements.
  10. Targeting Changes: Campaign targeting should be maintained at the application level, but it also allows pubs to control the placement-level, including:
  11. Offer limits managed per placement instead of per application.
  12. Campaign filtering based on placement configurations.
  13. Unified Player Identity: Each player will have a single AdGem UID per application, enabling them to navigate between placements to view offers, earn coins, and access different languages without creating multiple identities.
  14. Match 1:1 Representation with Publisher's apps: The multi-app setup should be maintained, this way publishers with more than one app can have one AdGem App for each application they have.

Proposed Architecture (Placements)

graph TB subgraph "Publisher App" Player["Player<br/>(externalPlayerId)"] end subgraph "AdGem - New Placement-Based Structure" App["Application<br/>(Parent Entity)"] subgraph "Placements (Children)" P1["Placement 1<br/>USD, 1x multiplier<br/>Main Screen"] P2["Placement 2<br/>EUR, 2x multiplier<br/>Rewards Screen"] P3["Placement 3<br/>USD, 1x multiplier<br/>Spanish Language"] P4["Placement 4<br/>GBP, 1.5x multiplier<br/>Side Menu"] end UID["AdGem UID<br/>(One per App)"] end subgraph "AdTracking" ATP["Player Record"] RW1["Reward 1"] RW2["Reward 2"] RW3["Reward 3"] RW4["Reward 4"] ATP --> RW1 ATP --> RW2 ATP --> RW3 ATP --> RW4 end subgraph "Offers & Targeting" Offers["Available Offers"] Targeting["Placement-Level<br/>Targeting Rules"] end Player -->|"Creates Once"| UID UID --> App UID --> ATP App -->|"1:n"| P1 App -->|"1:n"| P2 App -->|"1:n"| P3 App -->|"1:n"| P4 Player -."Navigates".-> P1 Player -."Navigates".-> P2 Player -."Navigates".-> P3 Player -."Navigates".-> P4 P1 --> Targeting P2 --> Targeting P3 --> Targeting P4 --> Targeting Targeting --> Offers ATP -->|"Rewards"| Player style Player fill:#4ecdc4 style UID fill:#95e1d3 style ATP fill:#95e1d3 style App fill:#6c5ce7 style P1 fill:#a29bfe style P2 fill:#a29bfe style P3 fill:#a29bfe style P4 fill:#a29bfe style Offers fill:#fdcb6e style Targeting fill:#fd79a8

Key Improvements: - One player → One AdGem UID per application - Single player record in AdTracking. - Multiple placements as children of one application. - Player seamlessly navigates between placements. - Simplified reward and transaction management. - Proper database schema representation (2NF compliant). - Placement-level targeting without identity fragmentation.

Implementation Flow

sequenceDiagram participant P as Player participant PA as Publisher App participant API as AdGem API participant DB as Database participant AT as Player API Note over P,AT: Initial Player Registration P->>PA: Opens App PA->>API: Register Player (externalPlayerId, appId) API->>AT: Check if AdGem UID exists for App alt UID Does Not Exist AT->>API: No UID found API->>AT: Create Player Record else UID Exists AT->>API: Return existing UID end API->>PA: Return AdGem UID Note over P,AT: Accessing Different Placements P->>PA: Navigate to Placement 1 (USD, Main Screen) PA->>API: Get Offers (adGemUID, placementId: P1) API->>DB: Fetch Placement Config & Targeting API->>DB: Apply Placement-Level Offer Limits API->>PA: Return Filtered Offers (USD) P->>PA: Navigate to Placement 2 (EUR, Rewards Screen) PA->>API: Get Offers (adGemUID, placementId: P2) Note right of API: Same UID, different placement API->>DB: Fetch Placement Config & Targeting API->>PA: Return Filtered Offers (EUR, 2x multiplier) Note over P,AT: Reward Management P->>PA: Completes Offer in Placement 1 PA->>API: Track Conversion (adGemUID, placementId: P1) API->>AT: Record Event (Single Player Record) API->>DB: Update Rewards (Single UID) API->>PA: Conversion Tracked PA->>P: Display Reward (based on P1 multiplier)

Flow Benefits: - Single UID creation and reuse across all placements. - Placement context passed in each API call. - No external Player ID dependency for tracking. - Simplified reward calculation with placement-specific multipliers. - Consistent player identity across all interactions.

CONSEQUENCES

Positive Outcomes

  1. Improved Tracking Accuracy: With a one-to-one relationship between players and applications, tracking becomes more reliable and accurate.
  2. Simplified Player Identity Management: A single AdGem UID per application eliminates confusion and reduces database complexity.
  3. Better Reward Management: Easier to track and manage player rewards and transactions without relying on external factors.
  4. Reduced API Complexity: Fewer redundant API calls and simpler request/response handling.
  5. Enhanced Flexibility: Publishers can create multiple placements for different use cases without fragmenting player identity.
  6. Scalability: The new structure scales better as it doesn't create database records exponentially with configuration variations.

Negative Outcomes

  1. Migration Effort: Existing applications and app-groups will need to be migrated to the new placement structure.
  2. Breaking Changes: Current API integrations may need updates to work with the new placement-based model.
  3. Learning Curve: Publishers and internal teams will need to learn the new placement concept and adjust their workflows. This also applies to the campaign team and the way they target campaigns to apps.
  4. Backward Compatibility: May need to maintain legacy support during transition period, increasing temporary complexity.
  5. Campaign Targeting Adjustments: Existing campaigns targeted at the application level will need reconfiguration for placement-level targeting.

Risks

  1. Data Migration Complexity: Risk of data loss or corruption during migration from app-groups to placements. Mitigation: Implement comprehensive migration scripts with rollback capabilities and extensive testing.

  2. Publisher Adoption: Publishers may resist the change or struggle with the new model. Mitigation: Provide comprehensive documentation, migration guides, and support during transition.

  3. Performance Impact: New placement lookup logic could impact API response times. Mitigation: Optimize AdGem PostgreSQL database queries and implement appropriate caching strategies.

  4. Integration Breakage: Third-party integrations relying on the current app-group structure may break. Mitigation: Provide deprecation notices, maintain a backward compatibility layer, and offer migration support.

  5. Incomplete Feature Parity: Placements may initially lack some functionality available in app-groups. Mitigation: Conduct thorough feature mapping and implement all critical features before migration.

  6. Tracking Gaps During Transition: Potential for tracking inconsistencies during the migration period. Mitigation: Implement dual-tracking temporarily and validate data integrity before fully transitioning.

NOTES

  • 2026/02/23
    • Deferred for other priorities and its inherent complexity.
    • This would be revisited when the new Publisher self-service portal starts to be developed.

References

Original Author

M Cornejo Q Soto

Approval date

Approved by