Skip to main content

Language Examples

Ready-to-use helper functions and examples for integrating Eventicat into your application. All examples use environment variables for secure credential management.

Environment Setup​

Store your credentials as environment variables:

export EVENTICAT_AGGREGATOR_ID="your_aggregator_id"
export EVENTICAT_API_KEY="your_api_key"

JavaScript/TypeScript​

Helper Function​

async function sendEvent(eventName, tags = {}) {
  const aggregatorId = process.env.EVENTICAT_AGGREGATOR_ID;
  const apiKey = process.env.EVENTICAT_API_KEY;

  const response = await fetch(
    `https://app.eventicat.com/api/event?_id=${aggregatorId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: eventName,
        ...tags
      })
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to send event: ${response.statusText}`);
  }

  return await response.json();
}

Usage​

// Simple event
await sendEvent('user_signup');

// Event with tags
await sendEvent('purchase_completed', {
  plan: 'pro',
  region: 'us-east'
});

Browser/Frontend (Next.js, React)​

For frontend applications, create an API route to proxy events:

// app/api/track/route.js
import { NextResponse } from 'next/server';

export async function POST(request) {
  const { name, ...tags } = await request.json();

  const response = await fetch(
    `https://app.eventicat.com/api/event?_id=${process.env.EVENTICAT_AGGREGATOR_ID}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.EVENTICAT_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name, ...tags })
    }
  );

  return NextResponse.json(await response.json(), { status: response.status });
}

Then call it from your frontend:

// Client-side code
async function trackEvent(name, tags = {}) {
  await fetch('/api/track', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name, ...tags })
  });
}

// Usage
await trackEvent('button_clicked', { button_id: 'signup' });

Python​

Helper Function​

import os
import requests

def send_event(event_name, tags=None):
    """Send an event to Eventicat."""
    aggregator_id = os.environ['EVENTICAT_AGGREGATOR_ID']
    api_key = os.environ['EVENTICAT_API_KEY']

    payload = {'name': event_name}
    if tags:
        payload.update(tags)

    response = requests.post(
        f'https://app.eventicat.com/api/event?_id={aggregator_id}',
        headers={
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        },
        json=payload
    )

    response.raise_for_status()
    return response.json()

Usage​

# Simple event
send_event('user_signup')

# Event with tags
send_event('purchase_completed', {
    'plan': 'pro',
    'region': 'us-east'
})

Django Integration​

# utils/analytics.py
import os
import requests
from django.conf import settings

def track_event(event_name, tags=None):
    """Track an event in Eventicat."""
    aggregator_id = settings.EVENTICAT_AGGREGATOR_ID
    api_key = settings.EVENTICAT_API_KEY

    payload = {'name': event_name}
    if tags:
        payload.update(tags)

    try:
        response = requests.post(
            f'https://app.eventicat.com/api/event?_id={aggregator_id}',
            headers={
                'Authorization': f'Bearer {api_key}',
                'Content-Type': 'application/json'
            },
            json=payload,
            timeout=5
        )
        response.raise_for_status()
    except requests.RequestException as e:
        # Log error but don't break user flow
        print(f"Analytics error: {e}")

# views.py
from .utils.analytics import track_event

def signup_view(request):
    # ... handle signup ...
    track_event('user_signup', {'source': 'web'})

PHP​

Helper Function​

<?php
function sendEvent($eventName, $tags = []) {
    $aggregatorId = getenv('EVENTICAT_AGGREGATOR_ID');
    $apiKey = getenv('EVENTICAT_API_KEY');

    $payload = array_merge(['name' => $eventName], $tags);

    $ch = curl_init("https://app.eventicat.com/api/event?_id={$aggregatorId}");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 201) {
        throw new Exception("Failed to send event: HTTP {$httpCode}");
    }

    return json_decode($response, true);
}

Usage​

<?php
// Simple event
sendEvent('user_signup');

// Event with tags
sendEvent('purchase_completed', [
    'plan' => 'pro',
    'region' => 'us-east'
]);

Laravel Integration​

<?php
// app/Services/EventicatService.php
namespace App\Services;

use Illuminate\Support\Facades\Http;

class EventicatService
{
    public function track(string $eventName, array $tags = []): void
    {
        $aggregatorId = config('services.eventicat.aggregator_id');
        $apiKey = config('services.eventicat.api_key');

        try {
            Http::withHeaders([
                'Authorization' => "Bearer {$apiKey}",
                'Content-Type' => 'application/json'
            ])->post("https://app.eventicat.com/api/event?_id={$aggregatorId}", [
                'name' => $eventName,
                ...$tags
            ])->throw();
        } catch (\Exception $e) {
            // Log error but don't break user flow
            logger()->error("Eventicat tracking error: {$e->getMessage()}");
        }
    }
}

// Usage in controller
use App\Services\EventicatService;

class UserController extends Controller
{
    public function store(Request $request, EventicatService $eventicat)
    {
        // ... create user ...

        $eventicat->track('user_signup', [
            'source' => $request->input('source', 'web')
        ]);
    }
}

Ruby​

Helper Function​

require 'net/http'
require 'json'
require 'uri'

def send_event(event_name, tags = {})
  aggregator_id = ENV['EVENTICAT_AGGREGATOR_ID']
  api_key = ENV['EVENTICAT_API_KEY']

  uri = URI("https://app.eventicat.com/api/event?_id=#{aggregator_id}")

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = "Bearer #{api_key}"
  request['Content-Type'] = 'application/json'
  request.body = { name: event_name }.merge(tags).to_json

  response = http.request(request)

  raise "Failed to send event: #{response.code}" unless response.code == '201'

  JSON.parse(response.body)
end

Usage​

# Simple event
send_event('user_signup')

# Event with tags
send_event('purchase_completed', {
  plan: 'pro',
  region: 'us-east'
})

Rails Integration​

# app/services/eventicat_service.rb
class EventicatService
  def self.track(event_name, tags = {})
    aggregator_id = Rails.application.credentials.eventicat[:aggregator_id]
    api_key = Rails.application.credentials.eventicat[:api_key]

    uri = URI("https://app.eventicat.com/api/event?_id=#{aggregator_id}")

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(uri)
    request['Authorization'] = "Bearer #{api_key}"
    request['Content-Type'] = 'application/json'
    request.body = { name: event_name }.merge(tags).to_json

    response = http.request(request)

    Rails.logger.error("Eventicat error: #{response.code}") unless response.code == '201'
  rescue StandardError => e
    Rails.logger.error("Eventicat error: #{e.message}")
  end
end

# Usage in controller
class UsersController < ApplicationController
  def create
    # ... create user ...

    EventicatService.track('user_signup', source: 'web')
  end
end

Go​

Helper Function​

package eventicat

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type EventPayload struct {
    Name string                 `json:"name"`
    Tags map[string]interface{} `json:",inline"`
}

func SendEvent(eventName string, tags map[string]interface{}) error {
    aggregatorID := os.Getenv("EVENTICAT_AGGREGATOR_ID")
    apiKey := os.Getenv("EVENTICAT_API_KEY")

    payload := EventPayload{
        Name: eventName,
        Tags: tags,
    }

    if payload.Tags == nil {
        payload.Tags = make(map[string]interface{})
    }

    jsonData, err := json.Marshal(payload)
    if err != nil {
        return fmt.Errorf("failed to marshal payload: %w", err)
    }

    url := fmt.Sprintf("https://app.eventicat.com/api/event?_id=%s", aggregatorID)

    req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    if err != nil {
        return fmt.Errorf("failed to create request: %w", err)
    }

    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("failed to send request: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusCreated {
        return fmt.Errorf("unexpected status code: %d", resp.StatusCode)
    }

    return nil
}

Usage​

package main

import (
    "log"
    "yourapp/eventicat"
)

func main() {
    // Simple event
    err := eventicat.SendEvent("user_signup", nil)
    if err != nil {
        log.Printf("Failed to track event: %v", err)
    }

    // Event with tags
    err = eventicat.SendEvent("purchase_completed", map[string]interface{}{
        "plan":   "pro",
        "region": "us-east",
    })
    if err != nil {
        log.Printf("Failed to track event: %v", err)
    }
}

Rust​

Helper Function​

use reqwest;
use serde_json::json;
use std::collections::HashMap;
use std::env;

pub async fn send_event(
    event_name: &str,
    tags: Option<HashMap<String, String>>
) -> Result<(), Box<dyn std::error::Error>> {
    let aggregator_id = env::var("EVENTICAT_AGGREGATOR_ID")?;
    let api_key = env::var("EVENTICAT_API_KEY")?;

    let url = format!("https://app.eventicat.com/api/event?_id={}", aggregator_id);

    let mut payload = json!({
        "name": event_name
    });

    if let Some(tags_map) = tags {
        for (key, value) in tags_map {
            payload[key] = json!(value);
        }
    }

    let client = reqwest::Client::new();
    let response = client
        .post(&url)
        .header("Authorization", format!("Bearer {}", api_key))
        .header("Content-Type", "application/json")
        .json(&payload)
        .send()
        .await?;

    if !response.status().is_success() {
        return Err(format!("Failed with status: {}", response.status()).into());
    }

    Ok(())
}

Usage​

use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Simple event
    send_event("user_signup", None).await?;

    // Event with tags
    let mut tags = HashMap::new();
    tags.insert("plan".to_string(), "pro".to_string());
    tags.insert("region".to_string(), "us-east".to_string());

    send_event("purchase_completed", Some(tags)).await?;

    Ok(())
}

Best Practices​

Error Handling​

Always handle errors gracefully. Analytics should never break your user's experience:

// Good: Silent failure with logging
async function sendEvent(eventName, tags = {}) {
  try {
    const response = await fetch(/* ... */);
    if (!response.ok) {
      console.error('Event tracking failed:', response.statusText);
    }
  } catch (error) {
    console.error('Event tracking error:', error);
  }
}

Timeouts​

Set reasonable timeouts to prevent slow analytics from blocking your application:

# Python with timeout
response = requests.post(
    url,
    headers=headers,
    json=payload,
    timeout=5  # 5 second timeout
)

Async Tracking​

For better performance, send events asynchronously:

// Fire and forget
sendEvent('page_view').catch(err => console.error(err));

// Don't await in request handlers
app.post('/signup', async (req, res) => {
  const user = await createUser(req.body);
  sendEvent('user_signup'); // No await
  res.json({ success: true });
});

Environment Configuration​

Use .env files for local development:

# .env
EVENTICAT_AGGREGATOR_ID=your_aggregator_id
EVENTICAT_API_KEY=your_api_key

For production, use your platform's secret management:

  • Vercel/Netlify: Environment variables in dashboard
  • AWS: Systems Manager Parameter Store or Secrets Manager
  • Docker: --env-file or secrets
  • Kubernetes: ConfigMaps and Secrets

Next Steps​