Skip to main content

Installation Guide

This guide provides detailed instructions for integrating the Cirvia Parental SDK into your Android project. Follow these steps to add intelligent content moderation to your app.

System Requirements​

Minimum Requirements​

  • Android Studio: 4.0 or higher
  • Gradle: 6.5 or higher
  • Minimum SDK: API Level 21 (Android 5.0)
  • Target SDK: API Level 34 (Android 14)
  • Java: 8 or higher
  • Kotlin: 1.5.0 or higher (optional)
  • Android Studio: Latest stable version
  • Gradle: Latest stable version
  • Target SDK: Latest Android API level

Step 1: Project Setup​

Add Repository (if needed)​

If you're using a private repository, add this to your project-level build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        // Add if using private repo
        maven {
            url "https://your-private-repo-url"
            credentials {
                username = "your-username"
                password = "your-password"
            }
        }
    }
}

Module-level build.gradle​

Add these dependencies to your app's build.gradle file:

android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        targetSdk 34
        // ... other config
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    // Required dependencies
    implementation 'com.squareup.okhttp3:okhttp:4.9.3'
    implementation 'com.google.code.gson:gson:2.8.9'
    implementation 'com.google.android.gms:play-services-auth:20.4.1'
    
    // Optional but recommended
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'androidx.core:core-ktx:1.9.0'
}

Step 2: Permissions​

Add required permissions to your AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.yourpackage.yourapp">

    <!-- Required: Internet access for API calls -->
    <uses-permission android:name="android.permission.INTERNET" />
    
    <!-- Required: Network state to check connectivity -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
    <!-- Optional: Camera permission if monitoring camera content -->
    <uses-permission android:name="android.permission.CAMERA" />
    
    <!-- Optional: Storage permission if processing local images -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme">
        <!-- Your activities here -->
    </application>
</manifest>

Required Permissions Explained​

  • INTERNET: Essential for API communication with Cirvia servers
  • ACCESS_NETWORK_STATE: Allows checking if device is connected to internet
  • CAMERA: Only needed if your app monitors camera/photo content
  • READ_EXTERNAL_STORAGE: Only needed if processing images from device storage

Step 3: Google Services Setup​

Download google-services.json​

  1. Go to the Firebase Console
  2. Create a new project or select existing project
  3. Add your Android app to the project
  4. Download google-services.json
  5. Place it in your app's app/ directory

Add Google Services Plugin​

Add to your project-level build.gradle:

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.3.15'
    }
}

Add to your app-level build.gradle:

plugins {
    id 'com.android.application'
    id 'com.google.gms.google-services'  // Add this line
}

Step 4: ProGuard Configuration​

If you're using ProGuard or R8, add these rules to your proguard-rules.pro:

# Cirvia Parental SDK
-keep class com.cirvia.parentalai.** { *; }
-keepclassmembers class com.cirvia.parentalai.** { *; }

# OkHttp
-dontwarn okhttp3.**
-dontwarn okio.**
-dontwarn javax.annotation.**

# Gson
-keepattributes Signature
-keepattributes *Annotation*
-dontwarn sun.misc.**
-keep class com.google.gson.** { *; }
-keep class * implements com.google.gson.TypeAdapterFactory
-keep class * implements com.google.gson.JsonSerializer
-keep class * implements com.google.gson.JsonDeserializer

# Google Play Services
-keep class com.google.android.gms.** { *; }
-dontwarn com.google.android.gms.**

Step 5: Initialize SDK​

Basic Initialization​

Create a configuration and initialize in your Application class or main Activity:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        // Initialize Cirvia Parental SDK
        ParentalAIConfig config = new ParentalAIConfig(
            "your-api-key-here",           // Provided upon partnership approval
            "your-ingest-endpoint-here",   // Provided upon partnership approval  
            "your-auth-endpoint-here",     // Provided upon partnership approval
            BuildConfig.DEBUG              // Enable debug logging in debug builds
        );
        
        ParentalAI.init(this, config, 
            () -> Log.d("ParentalAI", "SDK initialized successfully"),
            () -> Log.e("ParentalAI", "SDK initialization failed")
        );
    }
}

Register Application Class​

Don't forget to register your Application class in AndroidManifest.xml:

<application
    android:name=".MyApplication"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme">
    <!-- Activities here -->
</application>

Step 6: API Key Configuration​

Obtain API Key & Endpoints​

  1. Contact Cirvia support at info@cirvia.co to establish a developer partnership
  2. Provide your app package name, use case, and expected user volume
  3. Upon successful partnership approval, you'll receive:
    • Your unique API key
    • Ingestion endpoint URL
    • Authentication endpoint URL

Secure API Key Storage​

Store your API key securely:

Option 1: Environment Variables (Recommended)

In your gradle.properties:

CIRVIA_API_KEY=your_actual_api_key_here

In your build.gradle:

android {
    defaultConfig {
        buildConfigField "String", "CIRVIA_API_KEY", "\"${CIRVIA_API_KEY}\""
    }
}

Option 2: String Resources

In res/values/strings.xml:

<resources>
    <string name="cirvia_api_key" translatable="false">your_api_key_here</string>
</resources>

Step 7: Test Installation​

Create a simple test to verify everything is working:

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        // Test SDK functionality
        testSDK();
    }
    
    private void testSDK() {
        // Send a test incident
        ParentalAI.sendTextIncident("test-platform", "This is a test message");
        Log.d("MainActivity", "Test incident sent successfully");
    }
}

Troubleshooting​

Common Issues​

Build Error: "Could not resolve dependencies"

  • Ensure you have the correct repositories in your build.gradle
  • Check your internet connection
  • Sync project with Gradle files

Runtime Error: "SDK not initialized"

  • Make sure you call ParentalAI.init() before using other methods
  • Check that your API key is valid
  • Verify network permissions are granted

Google Sign-In Issues

  • Ensure google-services.json is in the correct location
  • Verify SHA1 fingerprint is registered in Firebase Console
  • Check package name matches Firebase configuration

Debug Mode​

Enable debug logging to troubleshoot issues:

ParentalAIConfig config = new ParentalAIConfig(
    apiKey,
    ingestEndpoint,
    authEndpoint,
    true  // Enable debug logging
);

Check logs for detailed error messages:

adb logcat | grep ParentalAI

Next Steps​

Now that installation is complete:

  1. Authentication Setup → - Configure Google OAuth
  2. API Reference → - Learn about all available methods
  3. Platform Integration → - Platform-specific examples
  4. Text Monitoring → - Monitor chat and messages

Getting Help​

Installation complete? Continue to Authentication Setup to configure Google OAuth.