Analytics

Give Octopus analytics more context about your users, and observe the events the SDK emits while they use the community.

Before you begin

• Complete the Quickstart: the SDK is initialized.
• To forward the events of the SDK, have your own analytics tool set up in your app.
• To report the cohort of your own A/B test, see A/B testing.

How it works

Analytics flows in two directions:

	Custom events	Events of the SDK
Direction	Your app → Octopus analytics	The SDK → your app
What it carries	Events you define, with a free-form name and string properties	What the user does in the Octopus UI: posts, reactions, screens, sessions…
Where it goes	Octopus analytics	Your code only: the SDK sends these events nowhere. You decide whether to forward them to your analytics tool.
Reference	Step 1	Step 2 and the events reference

You are responsible for what you send and forward:

• Never send sensitive data (health, religion, political opinions, sexual orientation, biometric or genetic data, criminal records), payment details, government ids, login credentials, or the content of private messages.
• Where privacy laws apply to your users (GDPR in the EEA and the UK, CCPA in California, LGPD in Brazil…), collect the consent they require before you send or forward analytics.

---

1. Send custom events

Define your own event types: there is no fixed catalog. Each event has a name and any properties you want to attach, and every property value is a string. Send as many types as your app needs, for example Purchase, SignUp, TutorialCompleted or AddToCart.

Android

• event: TrackerEvent.Custom — the event, with its name and its properties: Map<String, TrackerEvent.Custom.Property>.
• The function is suspend: call it from a coroutine.

scope.launch {
    OctopusSDK.track(
        event = TrackerEvent.Custom(
            name = "Purchase",
            properties = mapOf(
                "price" to TrackerEvent.Custom.Property(value = "1.99"),
                "currency" to TrackerEvent.Custom.Property(value = "EUR"),
                "product_id" to TrackerEvent.Custom.Property(value = "product1"),
            )
        )
    )

    // A different event type: send as many as you need
    OctopusSDK.track(
        event = TrackerEvent.Custom(
            name = "TutorialCompleted",
            properties = mapOf("level" to TrackerEvent.Custom.Property(value = "3"))
        )
    )
}

iOS

• customEvent: CustomEvent — the event, with its name and its properties: [String: CustomEvent.PropertyValue].
• The function is async throws.

Task {
    try await octopus.track(customEvent: CustomEvent(
        name: "Purchase",
        properties: [
            "price": .init(value: "1.99"),
            "currency": .init(value: "EUR"),
            "product_id": .init(value: "product1"),
        ]))

    // A different event type: send as many as you need
    try await octopus.track(customEvent: CustomEvent(
        name: "TutorialCompleted",
        properties: [
            "level": .init(value: "3"),
        ]))
}

Flutter

• name: String — the name of the event.
• properties: Map<String, String> — its properties.

await octopus.trackCustomEvent('Purchase', {
  'price': '1.99',
  'currency': 'EUR',
  'product_id': 'product1',
});

// A different event type: send as many as you need
await octopus.trackCustomEvent('TutorialCompleted', {
  'level': '3',
});

React Native

• name: string — the name of the event.
• properties: Record<string, string> — its properties. Convert numbers and booleans to strings.

import { trackCustomEvent } from '@octopus-community/react-native';

await trackCustomEvent('Purchase', {
  price: '1.99',
  currency: 'EUR',
  product_id: 'product1',
});

// A different event type: send as many as you need
await trackCustomEvent('TutorialCompleted', {
  level: '3',
});

Unity

• name: string — the name of the event.
• properties: IDictionary<string, string> — its properties.

OctopusSDK.Track("Purchase", new Dictionary<string, string>
{
    { "price", "1.99" },
    { "currency", "EUR" },
    { "product_id", "product1" }
});

// A different event type: send as many as you need
OctopusSDK.Track("TutorialCompleted", new Dictionary<string, string>
{
    { "level", "3" }
});

---

2. Listen to the events of the SDK

Android availableiOS availableFlutter availableReact Native availableUnity ≥ 1.12.2

What the user does inside the Octopus UI is otherwise invisible to your app. Subscribe to the events of the SDK to feed your own analytics tool with them. Every event and its fields are listed in the events reference.

Android

• OctopusSDK.events: Flow<OctopusEvent> — emits every event of the SDK.

// Convert Octopus events into events of your analytics tool,
// here Firebase Analytics
scope.launch {
    OctopusSDK.events.collect { event ->
        when (event) {
            is OctopusEvent.PostCreated -> {
                FirebaseAnalytics.getInstance(context).logEvent(
                    "post_created",
                    Bundle().apply {
                        putString("group", event.groupId)
                        putInt("text_length", event.textLength)
                        putBoolean("has_poll", OctopusEvent.PostCreated.Content.POLL in event.content)
                        putBoolean("has_image", OctopusEvent.PostCreated.Content.IMAGE in event.content)
                    }
                )
            }
            else -> Unit // Handle the other events
        }
    }
}

warning

collect never returns: launch it in a scope that lives as long as you need the events, for example an application-wide scope.

iOS

• octopus.eventPublisher: AnyPublisher<OctopusEvent, Never> — publishes every event of the SDK.

// Convert Octopus events into events of your analytics tool,
// here Firebase Analytics
octopus.eventPublisher
    .sink { event in
        switch event {
        case let .postCreated(context):
            Analytics.logEvent("post_created", parameters: [
                "group": context.groupId,
                "text_length": context.textLength,
                "has_poll": context.content.contains(.poll),
                "has_image": context.content.contains(.image),
            ])
        default:
            break // Handle the other events
        }
    }
    .store(in: &cancellables)

warning

Keep the AnyCancellable: without .store(in:), the subscription stops at once.

Flutter

• OctopusSDK.events: Stream<OctopusEvent> — emits every event of the SDK.

// Convert Octopus events into events of your analytics tool,
// here Firebase Analytics
final subscription = OctopusSDK.events.listen((event) {
  switch (event) {
    case PostCreatedEvent():
      FirebaseAnalytics.instance.logEvent(
        name: 'post_created',
        parameters: {
          'group': event.topicId ?? '', // The group id, named topicId on Flutter
          'text_length': event.textLength,
        },
      );
    default:
      break; // Handle the other events
  }
});

warning

Keep the StreamSubscription, and cancel() it when you no longer need the events.

React Native

• addSDKEventListener(callback) — calls callback with every event of the SDK. Returns a subscription to remove().

import { addSDKEventListener } from '@octopus-community/react-native';
import type { SDKEvent } from '@octopus-community/react-native';

// Convert Octopus events into events of your analytics tool
const subscription = addSDKEventListener((event: SDKEvent) => {
  switch (event.type) {
    case 'postCreated':
      analytics.logEvent('post_created', {
        group: event.groupId,
        text_length: event.textLength,
        has_poll: event.content.includes('poll'),
        has_image: event.content.includes('image'),
      });
      break;
    case 'gamificationPointsGained':
      analytics.logEvent('points_gained', {
        points: event.points,
        action: event.action,
      });
      break;
    default:
      break; // Handle the other events
  }
});

// Later, to unsubscribe
subscription.remove();

warning

Call subscription.remove() when you no longer need the events, for example when the component that subscribed unmounts.

Unity

• OctopusSDK.OnOctopusEvent: Action<OctopusEvent> — a static event raised for every event of the SDK.

using UnityEngine;
using UnityEngine.UI;

public class EventTracker : MonoBehaviour
{
    [SerializeField] Text statusText;

    void Start()
    {
        OctopusSDK.OnOctopusEvent += OnOctopusEvent;
    }

    void OnDestroy()
    {
        OctopusSDK.OnOctopusEvent -= OnOctopusEvent;
    }

    void OnOctopusEvent(OctopusEvent e)
    {
        // Runs on a background thread: do analytics and backend work here
        switch (e.Kind)
        {
            case OctopusEventKind.PostCreated:
                var post = (PostCreatedEvent)e;
                Debug.Log($"Post created in group {post.GroupId}, length {post.TextLength}");
                break;
            case OctopusEventKind.GamificationPointsGained:
                var points = (GamificationPointsGainedEvent)e;
                Debug.Log($"+{points.Points} points for {points.Action}");
                break;
        }

        // Marshal Unity UI updates to the main thread
        OctopusMainThread.Post(() =>
        {
            statusText.text = $"Last event: {e.Kind}";
        });
    }
}

warning

On a device, handlers run on a background thread: they must be thread-safe and must not call Unity APIs. Use OctopusMainThread.Post(action) to run work on the Unity main thread. On Android, the player loop is paused while the Octopus UI is open, so posted actions run when the user comes back to the game. In the Unity Editor Mock Mode, events are raised synchronously on the main thread instead.

---

See it in the samples

Android

The Octopus Sample app.

iOS

The Custom events and Events scenarios.

Flutter

The custom events and events scenarios of the example app.

React Native

The scenarios screen of the example app.

Unity

The CustomEventsScenario and EventsScenario scenarios of the Unity example.

Behavior and limits

• To have a new custom event type included in your reports, contact Octopus first so it can be set up.
• The events of the SDK only cover what the user does in the Octopus UI, and they are emitted in your app only.
• Only the gamification points earned or lost through an action of the user in the app are reported live.

Next steps

• Events reference — every event of the SDK, with its fields.
• A/B testing — measure the impact of the community.