or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

analytics.mdapi.mdauth.mddatastore.mdindex.mdnotifications.mdserver.mdstorage.mdutilities.md
tile.json

analytics.mddocs/

Analytics

Event tracking and user analytics with support for multiple providers including Amazon Pinpoint, Kinesis, Kinesis Firehose, and Amazon Personalize. Provides comprehensive user behavior tracking and analytics insights.

Capabilities

Core Import

import { record, identifyUser, enable, disable } from "aws-amplify/analytics";

For provider-specific functionality:

import { record, identifyUser } from "aws-amplify/analytics/pinpoint";
import { record } from "aws-amplify/analytics/kinesis";
import { record } from "aws-amplify/analytics/kinesis-firehose";
import { record } from "aws-amplify/analytics/personalize";

Event Recording

Record custom events and user interactions.

/**
 * Record an analytics event
 * @param input - Event data and configuration
 * @returns Promise that resolves when event is recorded
 */
function record(input: AnalyticsEvent | string): Promise<void>;

interface AnalyticsEvent {
  name: string;
  attributes?: Record<string, string>;
  metrics?: Record<string, number>;
  options?: {
    userId?: string;
    userIdRetentionDays?: number;
  };
}

Usage Examples:

import { record } from "aws-amplify/analytics";

// Simple event
await record("page_view");

// Event with attributes and metrics
await record({
  name: "purchase_completed",
  attributes: {
    product_id: "12345",
    product_category: "electronics",
    payment_method: "credit_card"
  },
  metrics: {
    purchase_amount: 99.99,
    quantity: 2
  }
});

// Event with user options
await record({
  name: "user_action",
  attributes: {
    action_type: "button_click",
    screen_name: "home"
  },
  options: {
    userId: "user123",
    userIdRetentionDays: 30
  }
});

User Identification

Identify users for analytics tracking.

/**
 * Identify a user for analytics tracking
 * @param input - User identification data
 * @returns Promise that resolves when user is identified
 */
function identifyUser(input: IdentifyUserInput): Promise<void>;

interface IdentifyUserInput {
  userId: string;
  userProfile?: UserProfile;
  options?: {
    userIdRetentionDays?: number;
  };
}

interface UserProfile {
  name?: string;
  email?: string;
  plan?: string;
  location?: {
    city?: string;
    country?: string;
    postalCode?: string;
    region?: string;
    latitude?: number;
    longitude?: number;
  };
  demographic?: {
    appVersion?: string;
    locale?: string;
    make?: string;
    model?: string;
    modelVersion?: string;
    platform?: string;
    platformVersion?: string;
    timezone?: string;
  };
  customProperties?: Record<string, string | number | boolean>;
}

Usage Example:

import { identifyUser } from "aws-amplify/analytics";

await identifyUser({
  userId: "user123",
  userProfile: {
    name: "John Doe",
    email: "john@example.com",
    plan: "premium",
    location: {
      city: "Seattle",
      country: "US",
      region: "WA"
    },
    demographic: {
      appVersion: "1.2.0",
      platform: "web",
      timezone: "America/Los_Angeles"
    },
    customProperties: {
      signup_date: "2023-01-15",
      total_purchases: 5,
      is_beta_user: true
    }
  },
  options: {
    userIdRetentionDays: 365
  }
});

Analytics Control

Enable and disable analytics tracking.

/**
 * Enable analytics tracking
 * @returns Promise that resolves when analytics is enabled
 */
function enable(): Promise<void>;

/**
 * Disable analytics tracking
 * @returns Promise that resolves when analytics is disabled
 */
function disable(): Promise<void>;

Usage Example:

import { enable, disable } from "aws-amplify/analytics";

// Enable analytics
await enable();

// Disable analytics (stops all tracking)
await disable();

Amazon Pinpoint Provider

Specialized analytics for Amazon Pinpoint with additional features.

// All core analytics functions are available with Pinpoint-specific implementations
// Plus additional Pinpoint-specific capabilities:

/**
 * Record event with Pinpoint-specific options
 */
function record(input: PinpointAnalyticsEvent): Promise<void>;

interface PinpointAnalyticsEvent extends AnalyticsEvent {
  options?: AnalyticsEvent['options'] & {
    /**
     * Pinpoint-specific configuration
     */
    pinpointConfig?: {
      /**
       * Custom endpoint configuration
       */
      endpoint?: {
        address?: string;
        attributes?: Record<string, string[]>;
        channelType?: 'EMAIL' | 'SMS' | 'PUSH' | 'CUSTOM';
        demographic?: {
          appVersion?: string;
          locale?: string;
          make?: string;
          model?: string;
          modelVersion?: string;
          platform?: string;
          platformVersion?: string;
          timezone?: string;
        };
        location?: {
          city?: string;
          country?: string;
          latitude?: number;
          longitude?: number;
          postalCode?: string;
          region?: string;
        };
        metrics?: Record<string, number>;
        optOut?: string;
        requestId?: string;
        user?: {
          userId?: string;
          userAttributes?: Record<string, string[]>;
        };
      };
    };
  };
}

Pinpoint Usage Example:

import { record, identifyUser } from "aws-amplify/analytics/pinpoint";

// Record event with Pinpoint-specific configuration
await record({
  name: "campaign_interaction",
  attributes: {
    campaign_id: "summer_sale_2023",
    interaction_type: "email_click"
  },
  options: {
    pinpointConfig: {
      endpoint: {
        channelType: 'EMAIL',
        address: 'user@example.com',
        attributes: {
          interests: ['electronics', 'sports'],
          preferences: ['email_notifications']
        }
      }
    }
  }
});

Amazon Kinesis Provider

Stream analytics data to Amazon Kinesis.

/**
 * Record event to Kinesis stream
 */
function record(input: KinesisAnalyticsEvent): Promise<void>;

interface KinesisAnalyticsEvent {
  streamName: string;
  data: Record<string, any>;
  partitionKey?: string;
}

Kinesis Usage Example:

import { record } from "aws-amplify/analytics/kinesis";

await record({
  streamName: "user-events-stream",
  data: {
    eventType: "page_view",
    timestamp: new Date().toISOString(),
    userId: "user123",
    pageUrl: "/dashboard",
    userAgent: navigator.userAgent
  },
  partitionKey: "user123"
});

Amazon Kinesis Firehose Provider

Stream analytics data to Kinesis Firehose for data warehouse integration.

/**
 * Record event to Kinesis Firehose delivery stream
 */
function record(input: FirehoseAnalyticsEvent): Promise<void>;

interface FirehoseAnalyticsEvent {
  deliveryStreamName: string;
  data: Record<string, any>;
}

Kinesis Firehose Usage Example:

import { record } from "aws-amplify/analytics/kinesis-firehose";

await record({
  deliveryStreamName: "analytics-delivery-stream",
  data: {
    event_name: "purchase_completed",
    user_id: "user123",
    timestamp: Date.now(),
    product_id: "prod456",
    amount: 29.99,
    currency: "USD"
  }
});

Amazon Personalize Provider

Record events for Amazon Personalize machine learning recommendations.

/**
 * Record event for Personalize recommendations
 */
function record(input: PersonalizeAnalyticsEvent): Promise<void>;

interface PersonalizeAnalyticsEvent {
  eventType: string;
  userId?: string;
  sessionId: string;
  itemId?: string;
  properties?: Record<string, string | number>;
  recommendationId?: string;
  impression?: string[];
}

Personalize Usage Example:

import { record } from "aws-amplify/analytics/personalize";

// Record item interaction
await record({
  eventType: "click",
  userId: "user123",
  sessionId: "session456",
  itemId: "item789",
  properties: {
    discount: 0.1,
    category: "electronics"
  }
});

// Record recommendation impression
await record({
  eventType: "view",
  userId: "user123", 
  sessionId: "session456",
  recommendationId: "rec123",
  impression: ["item1", "item2", "item3", "item4"]
});

Common Event Patterns

Standard event types and patterns for different use cases.

E-commerce Events:

// Product view
await record({
  name: "product_view",
  attributes: {
    product_id: "12345",
    product_name: "Wireless Headphones",
    category: "electronics",
    price: "99.99",
    currency: "USD"
  }
});

// Add to cart
await record({
  name: "add_to_cart",
  attributes: {
    product_id: "12345",
    quantity: "1"
  },
  metrics: {
    value: 99.99
  }
});

// Purchase
await record({
  name: "purchase",
  attributes: {
    transaction_id: "tx789",
    payment_method: "credit_card"
  },
  metrics: {
    total_amount: 199.98,
    tax_amount: 16.00,
    shipping_amount: 5.99
  }
});

App Usage Events:

// Screen view
await record({
  name: "screen_view",
  attributes: {
    screen_name: "dashboard",
    screen_class: "DashboardComponent"
  }
});

// Feature usage
await record({
  name: "feature_used",
  attributes: {
    feature_name: "export_data",
    feature_category: "data_management"
  }
});

// User engagement
await record({
  name: "session_start",
  metrics: {
    session_duration: 0
  }
});

Types

// Event configuration options
interface AnalyticsEventOptions {
  userId?: string;
  userIdRetentionDays?: number;
  immediate?: boolean;
  attributes?: Record<string, string>;
  metrics?: Record<string, number>;
}

// Error types
class AnalyticsError extends Error {
  name: 'AnalyticsError';
  message: string;
  cause?: Error;
}

// Provider-specific error types
class PinpointAnalyticsError extends AnalyticsError {
  name: 'PinpointAnalyticsError';
  endpointId?: string;
  applicationId?: string;
}

class KinesisAnalyticsError extends AnalyticsError {
  name: 'KinesisAnalyticsError';
  streamName?: string;
  sequenceNumber?: string;
}

Error Handling

Analytics operations can fail silently or throw errors:

import { record, AnalyticsError } from "aws-amplify/analytics";

try {
  await record({
    name: "custom_event",
    attributes: { key: "value" }
  });
} catch (error) {
  if (error instanceof AnalyticsError) {
    console.log('Analytics error:', error.message);
    // Event recording failed, but app can continue
  } else {
    console.log('Unexpected error:', error);
  }
}

// Analytics functions typically don't throw errors in production
// to avoid disrupting user experience, but will log errors for debugging

Best Practices

Event Naming

  • Use clear, descriptive event names like purchase_completed not event1
  • Use consistent naming conventions (snake_case or camelCase)
  • Include action and object: button_clicked, page_viewed, file_downloaded

Attribute Management

  • Keep attribute values as strings when possible
  • Use consistent attribute names across events
  • Avoid personally identifiable information in attributes

Performance

  • Batch events when possible rather than sending individually
  • Use appropriate user ID retention days to comply with privacy requirements
  • Consider disabling analytics in development/testing environments