Ncanto Interaction Logger

Overview

Ncanto Interaction Logger is a microservice designed to capture, normalize, and forward user interaction events to Ncanto's personalization and recommendation API. This documentation will help you understand how to integrate your client applications with the Interaction Logger.

Architecture

The Ncanto Interaction Logger follows a clean architecture with the following components:

Clients (Web, iOS, Android)
        │
        ▼
  API Gateway (Nginx)
        │
        ▼
  Flask API (POST /interact or /interact/batch)
        │
        ▼
   Redis Queue (async)
        │
        ▼
  Celery Worker → Ncanto API (POST /interactions)
        

API Endpoints

{
  "status": "success",
  "message": "Batch received and saved for processing",
  "count": 5,
  "skipped": 0
}
            

{
  "status": "ok",
  "uptime": 3600,
  "redis": true,
  "database": true,
  "pending_interactions": 0,
  "version": "1.0.0",
  "documentation": "/docs"
}
            

Interaction Standards

Guiding Principles

1. Unified Schema: All platforms (Web, iOS, Android) MUST follow a consistent JSON format and interaction naming convention.
2. Rating Signals: Actions are categorized as explicit (user intent) or implicit (behavior-derived). Each is mapped to a ratingEquivalent score.
3. Non-Blocking: Interactions should be "fire-and-forget" — no client-side retries or waiting on server responses.

VOD & Content Interactions (Viusasa, Citizen Digital)

E-Commerce Interactions (Duka)

Rating Equivalents

All interactions are mapped to a standardized rating scale from -1.0 to 1.0. This allows the recommendation engine to understand the relative strength of user preferences.

Payload Format

All interactions must follow this standardized JSON format:

{
  "timestamp": "2025-07-09T09:45:00Z",
  "subscriber": "product_user_12345",
  "assetId": "product_asset_67890",
  "interaction": "interaction_type",
  "ratingEquivalent": 0.25,
  "comment": "Optional: debug message",
  "contextId": "Optional: Ncanto context",
  "setting": {
    "device": "web" // Values: 'web', 'android_app', 'ios_app'
  }
}
        

Field Descriptions

Examples

Example 1: Video Playback Complete

{
  "timestamp": "2025-07-09T10:15:00Z",
  "subscriber": "viusasa_user_12345",
  "assetId": "viusasa_episode_67890",
  "interaction": "play_complete",
  "ratingEquivalent": 0.5,
  "comment": "User watched 90% of the episode.",
  "contextId": "viusasa_player_context",
  "setting": {
    "device": "android_app"
  }
}
        

Example 2: Add to Cart

{
  "timestamp": "2025-07-09T11:05:20Z",
  "subscriber": "duka_user_54321",
  "assetId": "duka_product_abcde",
  "interaction": "add_to_cart",
  "ratingEquivalent": 0.5,
  "comment": "User added product to cart from product detail page.",
  "contextId": "duka_pdp_context",
  "setting": {
    "device": "web"
  }
}
        

Example 3: Batch Request

[
  {
    "timestamp": "2025-07-09T09:30:00Z",
    "subscriber": "citizen_user_12345",
    "assetId": "citizen_article_67890",
    "interaction": "select",
    "ratingEquivalent": 0.25,
    "setting": {
      "device": "web"
    }
  },
  {
    "timestamp": "2025-07-09T09:31:00Z",
    "subscriber": "citizen_user_12345",
    "assetId": "citizen_article_67890",
    "interaction": "share",
    "ratingEquivalent": 0.75,
    "setting": {
      "device": "web"
    }
  }
]
        

Best Practices

When to Send Interactions

• Send interactions as they occur, in real-time
• For mobile apps, queue interactions when offline and send when connectivity is restored
• Use batch endpoint for sending multiple interactions at once (e.g., on app startup for queued events)

Error Handling

• Log failed requests locally for debugging
• Implement graceful degradation if the service is unavailable
• Do not block user experience while waiting for interaction logging

Performance Considerations

• Use the batch endpoint when sending multiple interactions
• Keep payloads as small as possible by omitting optional fields when not needed
• Consider using a client-side queue to batch interactions before sending

Security

• Always use HTTPS for all API requests
• Do not include sensitive user information in the payload
• Follow proper authentication methods as specified by the development team