Clix SDK Integration Skill

This skill provides comprehensive guidance for integrating Clix analytics SDK into mobile applications. Follow the workflow below to ensure proper installation and configuration.

Integration Strategy (MCP First)

This skill follows an "MCP First" strategy to ensure agents always use the latest verified SDK source code.

Step 1: Check for MCP Capability

• Check if the Clix MCP Server tools (

  clix-mcp-server:search_sdk

  ,

  clix-mcp-server:search_docs

  ) are available in your toolset.

Step 2: Primary Path (MCP Available)

• MUST use

  clix-mcp-server:search_sdk

  to fetch exact initialization code for the target platform (e.g.,

  clix-mcp-server:search_sdk(query="initialize", platform="android")

  ).
• Use these fetched results as the Single Source of Truth for implementation.
• Do NOT rely on static examples if MCP returns valid results.

Step 3: Fallback Path (MCP Unavailable)

• If checks for

  clix-mcp-server

  fail:
  1. Ask the user: "The Clix MCP Server is not detected. It provides the latest official SDK code. Would you like me to install it now?"
  2. If User says YES:
     • Run:

       bash scripts/install-mcp.sh --client <your-client>

     • The script will:
       • Verify the package is available
       • Configure the MCP server for the specified client
       • (If you omit

         --client

         and multiple clients are installed, the script will stop and ask you to choose.)
       • Automatically configure the MCP server in the appropriate config file
       • Provide clear instructions for restart
     • Instruct user to restart their agent/IDE to load the new server.
     • Stop here (let user restart).
  3. If User says NO:
     • Fall back to using the static patterns in

       references/framework-patterns.md

       and

       examples/

       .
     • Inform the user: "Proceeding with static fallback examples (may be outdated)."

Interaction Guidelines for Agents

When using this skill (for example inside OpenCode, Amp, Claude Code, Codex, Cursor, or other AI IDEs), follow these behaviors:

• Start with reconnaissance
  • Inspect the project structure first (list key files like

    package.json

    ,

    Podfile

    ,

    build.gradle

    ,

    pubspec.yaml

    ,

    AppDelegate.swift

    ,

    MainActivity.kt

    , etc.)
  • Clearly state what you detected (e.g., “This looks like a React Native project with iOS and Android”)
• Ask clarifying questions when needed
  • If multiple platforms are present, ask the user which one(s) to integrate first
  • If the structure is unusual, ask before making assumptions
• Explain each step briefly
  • Before making changes, say what you are about to do and why (install dependency, update entrypoint, add config, etc.)
  • Keep explanations short but concrete, so the user understands the impact
• Handle errors gracefully
  • If a command or change fails, show the error, explain likely causes, and suggest concrete next steps
  • Avoid getting stuck in loops—propose a fallback if automation fails
• End with a verification summary
  • Summarize what was installed/modified (files touched, dependencies added)
  • Point out any remaining manual steps (e.g., Xcode capabilities, Firebase config, running the app to test)

Integration Workflow

Phase 1: Prerequisite — Credentials (User Setup)

Before continuing, the user must ensure the following environment variables are available to the app at runtime:

• CLIX_PROJECT_ID

• CLIX_PUBLIC_API_KEY

How to get credentials:

• Ask the user to visit

  https://console.clix.so/

  and copy the values for their Clix project.

How to set credentials:

• Add them to a local

  .env

  file (recommended), or to your framework’s env configuration (see

  references/framework-patterns.md

  ).
• Ensure

  .env

  is in

  .gitignore

  .

Security warning:

• Do not paste credentials into chat. Enter them directly into the user’s terminal/editor.

Phase 2: Project Type Detection

Step 2.1: Identify Platform

Examine the codebase structure to determine platform:

• iOS: Look for

  .xcodeproj

  ,

  Podfile

  ,

  Info.plist

  , Swift/Objective-C files
• Android: Look for

  build.gradle

  ,

  AndroidManifest.xml

  , Kotlin/Java files
• Flutter: Look for

  pubspec.yaml

  ,

  lib/main.dart

  , plus

  ios/

  and

  android/

  folders
• React Native: Look for

  package.json

  with React Native dependencies,

  android/

  and

  ios/

  folders
• Other: If it’s not one of the above, stop and ask the user—this skill is mobile-only.

Priority rule (important): If React Native or Flutter is detected, treat it as the primary platform even if native

ios/

and

android/

folders exist.

Step 2.2: Verify Detection

Confirm platform detection with user if ambiguous:

• Multiple platforms detected (e.g., React Native has both iOS and Android)
• Unusual project structure
• Hybrid applications

Phase 3: SDK Installation

Step 3.1: Install SDK Package

Install the appropriate SDK based on detected platform:

iOS (Swift Package Manager):

// Add to Package.swift or Xcode: https://github.com/clix-so/clix-ios-sdk

iOS (CocoaPods):

# Add to Podfile
pod 'Clix', :git => 'https://github.com/clix-so/clix-ios-sdk.git'

Android (Gradle):

// Add to build.gradle.kts
implementation("so.clix:clix-android-sdk:latest")

React Native:

npm install @clix-so/react-native-sdk
# or
yarn add @clix-so/react-native-sdk

Flutter:

• Add the Clix Flutter SDK dependency in

  pubspec.yaml

  :

  dependencies:
    clix_flutter: ^0.0.1
    firebase_core: ^3.6.0
    firebase_messaging: ^15.1.3
  

• If MCP tools (

  search_docs

  ,

  search_sdk

  ) are available, use them to confirm the latest package version and setup steps.

Step 3.2: Verify Installation

• Check that package appears in dependency files (

  package.json

  ,

  Podfile.lock

  ,

  build.gradle

  )
• Verify import/require statements work
• Check for installation errors

Phase 4: SDK Initialization

Step 4.1: Locate Entry Point

Find the appropriate initialization location:

• iOS:

  AppDelegate.swift

  or

  @main

  app file
• Android:

  Application.kt

  or

  Application.java

  class
• Flutter:

  lib/main.dart

• React Native: Root component or

  index.js

Step 4.2: Initialize SDK

Add initialization code following platform-specific patterns (see examples/ directory):

Key Requirements:

• Initialize early in application lifecycle
• Use environment variables for credentials (never hardcode)
• Handle initialization errors gracefully
• Follow framework-specific best practices

Step 4.3: Configure SDK

Set up SDK configuration:

• Use

  CLIX_PROJECT_ID

  from environment variables
• Use

  CLIX_PUBLIC_API_KEY

  from environment variables
• Set appropriate environment (production/staging/development)
• Configure logging level if needed
• Enable/disable features as required

Phase 5: Integration Verification

Step 5.1: Code Review

Verify integration completeness:

• SDK is imported/required correctly
• Initialization code is in correct location
• Credentials are loaded from environment variables
• Error handling is implemented
• No hardcoded credentials

Step 5.2: Verify Integration

Run validation checks:

• Execute

  scripts/validate-sdk.sh

  if available
• Check that SDK initializes without errors
• Verify environment variables are accessible
• Verify SDK is properly imported and initialized

Platform Verification Checklists (UI Steps → Repo Verification)

Use these checklists to verify manual UI steps were actually completed.

iOS Verification

• Dependencies present:

  Podfile

  /

  Podfile.lock

  or SwiftPM/Xcode references
• Entitlements present: an

  *.entitlements

  file exists and is wired to the correct target(s)
• Capabilities configured:

  project.pbxproj

  reflects required capabilities (as applicable to Push Notifications / Background Modes)

Android Verification

• Dependencies present: module-level

  build.gradle

  /

  build.gradle.kts

  includes required SDK dependencies
• Manifest updated:

  AndroidManifest.xml

  contains required permissions, services/receivers (as required by the SDK)
• Firebase config placed (if used):

  google-services.json

  exists in the expected module directory (commonly

  app/

  )

React Native Verification

• JS dependency:

  package.json

  includes the Clix package
• iOS native:

  ios/Podfile.lock

  updated after

  pod install

  (when required)
• Android native: Gradle + Manifest updates present if required by the SDK
• Initialization: root entrypoint initializes the SDK exactly once

Flutter Verification

• Pub dependency:

  pubspec.yaml

  includes the required packages and

  pubspec.lock

  is updated after

  flutter pub get

• iOS native:

  ios/Podfile.lock

  updated after

  pod install

  (when required)
• Android native: Gradle + Manifest updates present if required
• Initialization: SDK initialized before

  runApp

Step 5.3: Documentation

Create or update documentation:

• Add integration notes to README.md
• Document environment variables needed
• Note any framework-specific considerations
• Update

  .env.example

  if it exists

Framework-Specific Patterns

iOS (Swift)

Initialization Pattern:

import Clix

@main
struct MyApp: App {
    init() {
        // Load credentials from your app configuration (do NOT hardcode).
        // Example: store values in Info.plist keys.
        let projectId = Bundle.main.object(forInfoDictionaryKey: "CLIX_PROJECT_ID") as? String ?? ""
        let apiKey = Bundle.main.object(forInfoDictionaryKey: "CLIX_PUBLIC_API_KEY") as? String

        let config = ClixConfig(projectId: projectId, apiKey: apiKey)
        Clix.initialize(config: config)
    }
}

Key Points:

• Initialize in

  @main

  app struct or

  AppDelegate

• Use environment variables, never hardcode
• Handle optional API key for analytics-only mode

Android (Kotlin)

Initialization Pattern:

import so.clix.core.Clix
import so.clix.core.ClixConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Load credentials from BuildConfig (do NOT hardcode).
        val config = ClixConfig.Builder()
            .projectId(BuildConfig.CLIX_PROJECT_ID)
            .apiKey(BuildConfig.CLIX_PUBLIC_API_KEY)
            .build()

        Clix.initialize(this, config)
    }
}

Key Points:

• Initialize in

  Application.onCreate()

• Use

  Application

  context, not Activity context
• Register Application class in

  AndroidManifest.xml

React Native

Initialization Pattern:

import { Clix } from "@clix-so/react-native-sdk";
import Config from "react-native-config";

// In App.tsx or index.js
Clix.initialize({
  projectId: Config.CLIX_PROJECT_ID || "",
  apiKey: Config.CLIX_PUBLIC_API_KEY,
});

Key Points:

• Initialize in root component
• Use

  react-native-config

  (or similar) for environment variables
• Link native dependencies if needed

Flutter

Initialization Pattern:

import 'package:clix_flutter/clix_flutter.dart';

Future<void> main() async {
  // Load credentials from build-time configuration (do NOT hardcode).
  // Example:
  // flutter run --dart-define=CLIX_PROJECT_ID=... --dart-define=CLIX_PUBLIC_API_KEY=...
  const projectId = String.fromEnvironment('CLIX_PROJECT_ID');
  const apiKey = String.fromEnvironment('CLIX_PUBLIC_API_KEY');

  await Clix.initialize(
    ClixConfig(
      projectId: projectId,
      apiKey: apiKey,
    ),
  );

  runApp(const MyApp());
}

Key Points:

• Initialize before

  runApp

• Use

  --dart-define

  (or your chosen secret mechanism), never hardcode

Error Handling

Common Issues:

1. Missing Credentials

   • Error: SDK fails to initialize
   • Solution: Verify

     .env

     file exists and contains required variables
   • Check: Environment variable names match exactly

2. Wrong Initialization Location

   • Error: SDK not tracking events
   • Solution: Ensure initialization happens before any SDK usage
   • Check: Initialization is in app entry point, not a component

3. Environment Variables Not Loading

   • Error:

     undefined

     or empty values
   • Solution: Verify env loading mechanism (dotenv, framework config, etc.)
   • Check: Variable names match framework requirements (prefixes)

Best Practices

1. Never hardcode credentials - Always use environment variables
2. Initialize early - SDK should initialize before app starts or as early as possible
3. Handle errors gracefully - Wrap initialization in try-catch blocks
4. Use appropriate environment - Set production/staging/development based on build
5. Verify integration - Use validation scripts to verify SDK is properly integrated
6. Document changes - Update README and configuration files
7. Version control - Add

   .env

   to

   .gitignore

   , commit

   .env.example

Docs Usage Note (MCP vs Static vs Web Docs)

• If MCP tools are available: treat

  search_sdk

  results as the source of truth for initialization/API usage.
• If MCP tools are unavailable: you may reference the official quickstarts below for manual steps, and use

  examples/

  +

  references/

  for code patterns.

Official quickstarts:

• iOS:

  https://docs.clix.so/sdk-quickstart-ios

• Android:

  https://docs.clix.so/sdk-quickstart-android

• React Native:

  https://docs.clix.so/sdk-quickstart-react-native

• Flutter:

  https://docs.clix.so/sdk-quickstart-flutter

Progressive Disclosure

• Level 1: This SKILL.md file (always loaded)
• Level 2:

  references/

  directory (loaded when needed for specific topics)
• Level 3:

  examples/

  directory (loaded when framework-specific examples needed)
• Level 4:

  scripts/

  directory (executed directly, not loaded into context)

References

For detailed information, see:

• references/sdk-reference.md

  - Complete SDK API documentation

• references/framework-patterns.md

  - Framework-specific integration patterns

• references/error-handling.md

  - Common errors and troubleshooting

• references/mcp-integration.md

  - Optional: MCP server usage guide (for tool-augmented mode)

Examples

Working code examples available in

examples/

directory:

• ios-integration.swift

  - iOS integration (UIKit/SwiftUI)

• android-integration.kt

  - Android integration (Application)

• flutter-integration.dart

  - Flutter integration (main.dart)

• react-native-integration.tsx

  - React Native integration (App.tsx)

Scripts

Utility scripts available in

scripts/

directory:

• validate-sdk.sh

  - Validate SDK installation and initialization (bash, deterministic)

Run scripts with

--help

first to see usage. Do not read source code unless customization is absolutely necessary.