Skip to main content

Feature Platform Integration Guide

Introduction​

This document estimates the integration effort required for a tenant to connect with the Feature Platform and explores ways to reduce this effort. While specific requirements may vary based on the tenant's existing infrastructure and technical capabilities, we'll focus on common integration points that most tenants will need to address.

Integration Points Overview​

There are two primary methods to send activity data to the Feature Platform:

  • Client-Side Tracking: Using our lightweight JavaScript SDK directly from the user's browser. (Recommended for most web applications.)
  • Server-Side Tracking: Sending data from your backend systems via our REST API. (Recommended for maximum reliability, mobile apps, or environments where client-side tracking isn't feasible.)

The following diagram illustrates both data flow paths and how they fit into your overall system architecture:

Integration Overview

This new diagram clarifies the two distinct integration paths. In the following sections, we'll delve into each integration point, offering effort estimates, detailed descriptions, and optimization opportunities to streamline your integration process.

End-to-End Data Flow​

Understanding the complete lifecycle of an event helps clarify the responsibilities of your system versus the Feature Platform.

Here is the standard flow for a "Watch-to-Earn" scenario:

  1. User Action: A user finishes watching a video on your website.
  2. Trigger: Your frontend (via Tracking SDK) or backend sends an activity event:
    • feature.track('video_completed', { videoId: '101' })
  3. Processing: Feature Platform receives the event (Status 202), validates rules (e.g., "Did they watch 90%?"), and triggers the blockchain issuance.
  4. Issuance: A digital asset is minted on the private chain to the user's custodial wallet.
  5. Notification: Feature Platform fires a activity.succeeded webhook to your backend.
  6. Resolution: Your backend validates the webhook signature and updates the user's UI (e.g., "You earned a Badge!").
  7. UI Notification: In turn your backend might notify your frontend.
  8. Headless Locker: Your frontend retrieves information about the digital asset using the Headless Locker API

End-to-End Data Flow

Integration Points in Detail​

Pattern A: Client-Side Integration via Tracking SDK (5 Steps)​

Pattern A (Tracking SDK) is recommended for modern web apps.

  1. Implement UI Event Handlers to call the SDK — see details: 1. UI Event Handlers.
  2. Install and initialize the SDK — see Tracking SDK.
  3. Set up your Webhook Endpoint — see details: 5. Webhook Receiving Endpoints and Webhooks.
  4. Implement Webhook Handling Logic — see details: 6. Webhook Handling Business Logic.
  5. Securely manage your keys — see details: 8. API Key Management.

This pattern simplifies tenant implementation by removing the need to build a dedicated backend endpoint for receiving UI requests, perform prerequisite validation inline, or manage API keys for client-originated event submission.

Pattern B: Server-Side Integration via Node.js SDK​

Pattern B (server-side) is for regulated / high-control / special infra.

  1. Implement UI Event Handlers to notify your backend — see details: 1. UI Event Handlers.
  2. Create an API Endpoint in your backend to receive these notifications — see details: 2. API Endpoint(s) for Receiving Requests from the UI.
  3. Implement your Prerequisite Validation Logic — see details: 3. Business Logic for Prerequisite Validation.
  4. Call Feature Platform SDK Methods — see details: 4. Using the Server-Side SDK.
  5. Set up your Webhook Endpoint — see details: 5. Webhook Receiving Endpoints and Webhooks.
  6. Implement Webhook Handling Logic — see details: 6. Webhook Handling Business Logic.
  7. Securely manage your keys — see details: 8. API Key Management.

Shared Integration Points (In Detail)​

1. UI Event Handlers to Capture Relevant User Interactions​

Effort Estimate: Low to Medium (varies based on existing UI and user interaction complexity)

Description: This integration point involves implementing or modifying event handlers in your user interface to capture relevant user interactions that trigger Feature Platform activities. The specific implementation depends on your application's nature and the types of user engagements you want to track.

Common scenarios include:

  1. Video Player Interactions:
    • Implement handlers for play, pause, seek, or video completion events.
    • Track viewing duration or percentage watched.
    • Capture interactions with interactive video elements.
  2. General Web Interactions:
    • Monitor clicks on specific UI elements (e.g., buttons, links).
    • Track form submissions or specific user inputs.
    • Measure time spent on particular pages or sections.
  3. Mobile App Interactions:
    • Capture app-specific gestures or interactions.
    • Monitor in-app purchase attempts or completions.
    • Track feature usage or navigation patterns.
  4. Game or Interactive Content:
    • Record progress, achievements, or level completions.
    • Capture social interactions within the game/content.
    • Monitor resource usage or in-game economy interactions.

These event handlers should collect relevant data about the interaction and prepare it for transmission to your backend API (covered in the next integration point).

Key Considerations:

  • Ensure event handlers are non-intrusive and don't impact the user experience.
  • Implement robust error handling and logging.
  • Address privacy implications and ensure compliance with relevant data protection regulations.
  • Optimize for performance, especially for high-frequency events.

By effectively implementing these UI event handlers, you'll ensure that all relevant user interactions are captured and can be leveraged within the Feature Platform to boost engagement and rewards.

5. Webhook Receiving Endpoints​

Effort Estimate: Medium

Set up secure HTTPS endpoints to receive asynchronous notifications (webhooks) from the Feature Platform. These webhooks deliver real-time updates on activity processing results (e.g., reward issuance, completion status).

Key considerations:

  1. Endpoint Setup
    • Accept POST requests over TLS; validate content type and size limits.
  2. Authentication
    • Verify signatures for each request; reject stale or invalid timestamps.
  3. Request Handling
    • Parse and validate payloads; handle malformed inputs safely.
  4. Asynchronous Processing
    • Acknowledge quickly (e.g., 2xx) and offload work to background jobs/queues.
  5. Idempotency
    • Ensure duplicate deliveries are safe to reprocess using unique IDs.
  6. Observability
    • Log all receipts; add metrics/alerts for failures and latency.
  7. Scalability & Resilience
    • Load-balance and implement retries/backoff for transient failures; provide a mechanism to reconcile missed events.

For payload formats and security details, see the dedicated Webhooks guide.

6. Webhook Handling Business Logic​

Effort Estimate: Medium to High

Implement the domain logic that updates your systems based on webhook events.

Typical responsibilities:

  1. Interpret Events
    • Route by type (e.g., reward_issued, activity_completed, error) and validate schema.
  2. Apply Business Rules
    • Update balances/inventories; unlock features; enqueue notifications.
  3. Data Integrity
    • Use atomic DB transactions; design for high-volume throughput.
  4. User Notifications
    • Trigger in-app, email, or push messages as appropriate.
  5. Consistency & Recovery
    • Periodically reconcile state with the platform; support retries and dead-letter flows.
  6. Testing & Monitoring
    • Provide fixtures/simulations; monitor success rates and latencies.

8. API Key Management​

Effort Estimate: Medium

Description: Develop a robust and secure system for storing, accessing, and managing API keys provided by the Feature Platform. Proper API key management is crucial for maintaining the security and integrity of your integration, protecting against unauthorized access, and ensuring smooth operations.

Key aspects of implementing API key management include:

  1. Secure Storage
    • Never store API keys in plaintext or version control systems.
    • Use encryption at rest to store API keys in a database or a dedicated secrets management solution.
    • For enhanced security, consider using a dedicated secrets management service like HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault.
  2. Access Control
    • Implement strict access controls to limit who can view or use the API keys.
    • Apply the principle of least privilege: only grant access to systems and personnel that require it.
    • Implement multi-factor authentication to access API key management systems.
  3. Key Rotation
    • Develop a process for regular API key rotation to mitigate the risk of compromised keys.
    • Implement a system that allows for seamless key rotation without service interruption.
    • Maintain a history of used keys for a limited time to handle any delayed operations.
  4. Monitoring and Auditing
    • Implement logging for all API key usage and access attempts.
    • Set up alerts for suspicious activities, such as unexpected high-volume usage or access attempts from unusual locations.
    • Regularly audit API key usage to ensure it aligns with expected patterns.
  5. Environment Separation
    • Use different API keys for development, staging, and production environments.
    • Ensure production keys are never used in non-production environments.
  6. Secure Distribution
    • Establish secure methods for distributing API keys to authorized systems and personnel.
    • Consider using ephemeral, time-bound tokens for temporary access needs.
  7. Emergency Response Plan
    • Develop and maintain an emergency response plan for compromised API keys.
    • Include steps for immediate key revocation and replacement.
  8. Integration with CI/CD
    • If using CI/CD pipelines, integrate secure methods for accessing API keys during automated processes.
    • Avoid storing API keys directly in CI/CD configuration files.
  9. Documentation and Training
    • Maintain clear documentation on API key management processes and best practices.
    • Provide regular training to team members on the importance of API key security.
  10. Compliance Considerations
  • Ensure your API key management practices comply with relevant industry standards and regulations (e.g., PCI DSS, GDPR).
  • Implement necessary controls and documentation to demonstrate compliance during audits.

Example implementation approach using a database (pseudo-code):

# Pseudo-code example for encrypted key storage
# Use a managed secrets solution or a vetted crypto library in production

class APIKeyManager:
    def __init__(self):
        self.encryption_key = ENV['ENCRYPTION_KEY']
        self.crypto = Crypto(self.encryption_key)  # placeholder for a real crypto helper

    def store_api_key(self, key_id, api_key):
        encrypted_key = self.crypto.encrypt(api_key)
        # Store key_id and encrypted_key in database

    def retrieve_api_key(self, key_id):
        # Retrieve encrypted_key from database
        decrypted_key = self.crypto.decrypt(encrypted_key)
        return decrypted_key

    def rotate_api_key(self, old_key_id, new_key_id, new_api_key):
        # Implement key rotation logic
        pass

While storing and retrieving API keys might seem straightforward, implementing a truly secure and robust API key management system demands careful consideration of various security aspects and operational needs. The medium effort estimate reflects the critical importance of getting this component right to ensure the overall security of your Feature Platform integration.

Server-Side Specific Points (In Detail)​

2. API Endpoint(s) for Receiving Requests from the UI​

Effort Estimate: Low to Medium (varies with existing infrastructure)

Description: This step involves capturing system events that trigger User Activities in the Feature Platform. The implementation approach depends on your current user action tracking:

  1. For systems already tracking relevant user actions:
    • New endpoints may not be necessary.
    • Integrate Feature Platform triggers into your existing event tracking system.
  2. For untracked UI user actions:
    • Implement server-side endpoint(s) to receive and process these UI events.
    • These endpoints will capture and prepare data for submission to the Feature Platform API.
  3. For relevant events in background processes:
    • No new endpoints are required.
    • Directly integrate Feature Platform triggers into your background job or process.

The aim is to ensure proper capture and processing of all relevant user actions or system events that initiate a User Activity in the Feature Platform, regardless of their origin in your system.

3. Business Logic for Prerequisite Validation​

Effort Estimate: Medium to High

Description: Develop logic within your system to validate prerequisites before initiating any interaction with the Feature Platform API. This crucial step ensures that only valid and eligible activities are sent to the Feature Platform, maintaining data integrity and reducing unnecessary API calls.

Key aspects of this validation logic include:

  • Checking user eligibility (e.g., account status, age restrictions, geographic location)
  • Verifying activity completion criteria (e.g., video watch time, purchase amount, interaction frequency)
  • Applying tenant-specific business rules or conditions
  • Ensuring data completeness and format correctness

This step's complexity can vary significantly based on your specific use case and existing business logic. In some cases, you can leverage existing validation processes in your system.

4. Using the Server-Side SDK​

Effort Estimate: Low

Description: Integrate the Feature Platform Node.js SDK into your backend. This SDK handles authentication and data formatting for you.

Steps:

  1. Install the SDK: npm install @feature/node-sdk
  2. Initialize: Create a client instance using your Admin API Key.
  3. Track: Use the client.track() method to send activity data.

Key considerations:

  • Error Handling: Wrap SDK calls in try/catch blocks.
  • Async/Await: The SDK methods are asynchronous.
  • Key Security: Ensure your Admin Key is loaded from environment variables and never committed to code.

7. Authentication​

Effort Estimate: Low (Handled by SDK)

Authentication is handled automatically by the SDK when you provide your Admin API Key during initialization. You do not need to manually sign requests or manage headers.

For webhook verification (verifying requests from Feature Platform to you), please refer to the Webhooks documentation.