Event Logging API Documentation

The event logging system is the core of our gamification platform. This guide explains how to use the /event endpoint and work with metadata effectively.

The /event Endpoint

The /event endpoint allows you to record user activities in your application that should earn points, contribute to streaks, or be tracked for analytics purposes.

Basic Usage of /event endpoint

GET https://api.lynesapp.de/v1/event

Authorization for the request

Include your JWT in the Authorization header. For more details, see the Authentication page.

Body of the /event request

{
  eventId: "daily_login", // Required: Identifier for the event type
  userId: "user123", // Required: User identifier
  metadata: {
    // Optional: Additional event data
    platform: "ios",
    appVersion: "2.1.4",
    sessionLength: 183,
  },
}

Required Fields

Please notice: You can send custom metadata to the /event endpoint optionally.

Working with Metadata

Metadata allows you to include rich contextual information with your events. This data is stored with the event and used for advanced analytics and conditional logic.

Why Use Metadata?

1. Enhanced Analytics: Track detailed information about how, when, and where events occur
2. Segmentation: Analyze user behavior based on metadata attributes
3. Conditional Rules: Create sophisticated event rules based on metadata values
4. Future-Proofing: Store potentially useful information without changing your core event structure

Metadata Best Practices

1. Be Consistent: Use the same field names across similar events
2. Use Appropriate Types:
   • Numbers for quantities, durations, and measurable values
   • Strings for categories, identifiers, and textual data
   • Booleans for flags and status indicators
3. Keep It Relevant: Only include data that provides meaningful context
4. Avoid PII: Never include personally identifiable information

Common Metadata Fields

When creating an event in the dashboard, you can add custom metadata fields. Metadata serves three main purposes:

1. Analytics: Gain deeper insights using metadata.
2. Conditional Events: Define conditions based on metadata (e.g., minimum purchase value or activity duration).
3. Value-Based Rewards: Reward users based on their spending (e.g., 2 points for every € spent).

Note: There is a limit of 10 metadata fields per request.

metadata: {
  // Device Context
  platform: 'android',         // Operating system/platform
  deviceType: 'mobile',        // Device category
  appVersion: '3.2.1',         // Application version
 
  // User Context
  usergroup: 'subscriber',       // Usergroup of the user (can be configured in the dashboard)
  accountAge: 63,              // Days since account creation
 
  // Event Details
  value: 29.99,                // For purchase events: monetary value
  itemId: 'premium_skin_12',   // For item interactions: which item
  duration: 145,               // For timed activities: seconds spent
  difficulty: 'hard',          // For challenges: difficulty level
}

How Metadata Is Processed

When you include metadata with your events:

1. The system automatically categorizes metadata fields by data type
2. Numeric fields are analyzed for min/max values, averages, and distributions
3. Categorical fields are analyzed for frequency counts and popular values
4. This aggregated data becomes available in your analytics dashboard
5. Trends and patterns in metadata can reveal important insights about usage

Example: E-commerce Purchase Event

// Purchase event with rich metadata
fetch("https://api.example.com/event", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    eventId: "purchase_completed",
    customerId: "user456",
    points: 50,
    metadata: {
      platform: "web",
      transactionId: "tx_78912345",
      orderValue: 129.99,
      currency: "USD",
      itemCount: 3,
      categories: ["electronics", "accessories"],
      isFirstPurchase: false,
      paymentMethod: "credit_card",
      couponUsed: true,
      discountAmount: 15.0,
    },
  }),
});

Example: Game Level Completion

// Game level completion with performance metadata
fetch("https://api.example.com/event", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    eventId: "level_completed",
    customerId: "gamer789",
    points: 25,
    metadata: {
      levelId: "world_2_level_5",
      difficulty: "normal",
      timeToComplete: 347, // seconds
      attempts: 2,
      starsEarned: 3,
      scoreAchieved: 12850,
      powerupsUsed: 2,
      platform: "ios",
      deviceModel: "iPhone 13",
      networkType: "wifi",
    },
  }),
});

Response Format

When logging an event successfully, you'll receive a response like this:

{
  "success": true,
  "data": {
    "eventId": "daily_login",
    "customerId": "user123",
    "pointsAwarded": 10,
    "timestamp": 1648232567123,
    "streaks": [
      {
        "streakId": "daily_app_use",
        "currentCount": 3,
        "lastUpdate": "2023-04-07T12:34:56.789Z",
        "milestoneReached": false,
        "pointsAwarded": 0
      }
    ]
  }
}

Error Handling

If there's an issue with your event logging request, you'll receive an error response:

{
  "success": false,
  "error": {
    "code": "INVALID_EVENT",
    "message": "Event ID not found or inactive"
  }
}

Common error scenarios:

• Missing required fields (eventId, customerId)
• Invalid event ID (the event doesn't exist in your configuration)
• Authentication errors (invalid or expired API key)
• Rate limiting (too many requests in a short time period)

Analytics Benefits

The metadata you provide with events enables rich analytics capabilities:

• Track event performance across different platforms and app versions
• Identify optimal user flows and conversion paths
• Discover which game levels need balancing based on completion times
• See which product categories drive the most engagement
• Understand how feature usage correlates with retention

By consistently including relevant metadata with your events, you'll build a valuable dataset that can drive product improvements and business decisions.