ParentalAI Class Reference

The ParentalAI class is the main entry point for the Cirvia Parental SDK. It provides static methods for initializing the SDK and monitoring content across your application.

Package

package com.cirvia.parentalai;

Class Declaration

public class ParentalAI

Overview

The ParentalAI class handles:

• SDK initialization and authentication
• Content monitoring (text and images)
• Communication with Cirvia backend services
• User session management

All methods are static and thread-safe, designed to be called from anywhere in your application.

Methods

init()

Initializes the Cirvia Parental SDK with user authentication flow.

Signature

public static void init(
    Context context, 
    ParentalAIConfig config, 
    Runnable onSuccess, 
    Runnable onDecline
)

Parameters

Parameter	Type	Description
context	Context	Android application context (Activity or Application)
config	ParentalAIConfig	Configuration object containing API keys and endpoints
onSuccess	Runnable	Callback executed when initialization succeeds
onDecline	Runnable	Callback executed when user declines or initialization fails

Behavior

1. Shows onboarding dialog to user explaining content moderation
2. If user agrees, initiates Google OAuth authentication flow
3. Exchanges Google ID token with Cirvia backend
4. Creates or retrieves user account
5. Calls appropriate callback based on result

Example

ParentalAIConfig config = new ParentalAIConfig(
    "your-api-key",
    "your-ingest-endpoint",
    "your-auth-endpoint", 
    BuildConfig.DEBUG
);

ParentalAI.init(this, config,
    () -> {
        Log.d("MyApp", "SDK ready for content monitoring");
        enableContentFeatures();
    },
    () -> {
        Log.w("MyApp", "User declined content monitoring");
        proceedWithoutModeration();
    }
);

Exceptions

Exception	Condition
IllegalArgumentException	If context or config is null
IllegalStateException	If SDK is already initialized

Thread Safety

This method must be called from the main/UI thread as it shows dialog UI.

---

sendTextIncident()

Reports a text content incident for AI moderation analysis.

Signature

public static void sendTextIncident(String platform, String rawContent)

Parameters

Parameter	Type	Description
platform	String	Platform identifier (e.g., "roblox", "discord", "my-app")
rawContent	String	The text content to analyze

Behavior

1. Creates an incident payload with text content
2. Sends content to AI moderation service asynchronously
3. Processes risk assessment and categorization
4. Stores incident in parent dashboard if risk threshold exceeded
5. Logs success/failure in debug mode

Example

// Monitor chat message
String userMessage = chatInput.getText().toString();
ParentalAI.sendTextIncident("my-social-app", userMessage);

// Monitor comment
String comment = commentField.getText().toString();
ParentalAI.sendTextIncident("roblox", comment);

// Monitor private message
String privateMsg = getPrivateMessage();
ParentalAI.sendTextIncident("discord", privateMsg);

Platform Identifiers

Use descriptive platform names for better parent dashboard experience:

Platform	Recommended ID
Roblox	"roblox"
Discord	"discord"
Instagram	"instagram"
TikTok	"tiktok"
Your App	"your-app-name"

Exceptions

Exception	Condition
IllegalStateException	If SDK not initialized
IllegalArgumentException	If platform or content is null/empty

Thread Safety

This method is thread-safe and executes network operations on background threads.

---

sendImageIncident()

Reports an image content incident for AI moderation analysis.

Signature

public static void sendImageIncident(String platform, String rawImgBase64)

Parameters

Parameter	Type	Description
platform	String	Platform identifier
rawImgBase64	String	Base64-encoded image data

Behavior

1. Creates an incident payload with image content
2. Sends image to AI moderation service asynchronously
3. Analyzes image for inappropriate content (nudity, violence, etc.)
4. Stores incident in parent dashboard if risk threshold exceeded
5. Logs success/failure in debug mode

Example

// Monitor uploaded photo
Bitmap userPhoto = getUserSelectedImage();
String base64Image = encodeImageToBase64(userPhoto);
ParentalAI.sendImageIncident("my-photo-app", base64Image);

// Monitor camera capture
public void onPictureTaken(byte[] data) {
    String base64Image = Base64.encodeToString(data, Base64.DEFAULT);
    ParentalAI.sendImageIncident("camera-app", base64Image);
}

// Monitor received image
public void onImageReceived(String imageUrl) {
    // Download and convert to base64
    String base64Image = downloadAndEncode(imageUrl);
    ParentalAI.sendImageIncident("messaging-app", base64Image);
}

Image Format Support

• Supported: JPEG, PNG, GIF, WebP
• Max Size: 10MB per image
• Recommended: Resize images to 1024x1024 or smaller for faster processing

Helper Method: Convert Bitmap to Base64

private String encodeImageToBase64(Bitmap bitmap) {
    ByteArrayOutputStream baos = new ByteArrayOutputStream();
    bitmap.compress(Bitmap.CompressFormat.JPEG, 80, baos);
    byte[] imageBytes = baos.toByteArray();
    return Base64.encodeToString(imageBytes, Base64.DEFAULT);
}

Exceptions

Exception	Condition
IllegalStateException	If SDK not initialized
IllegalArgumentException	If platform or image data is null/empty

Thread Safety

This method is thread-safe and executes network operations on background threads.

Usage Patterns

Application Lifecycle Integration

public class MyApplication extends Application {
    private boolean isSDKReady = false;
    
    @Override
    public void onCreate() {
        super.onCreate();
        initializeSDK();
    }
    
    private void initializeSDK() {
        ParentalAIConfig config = createConfig();
        ParentalAI.init(this, config,
            () -> isSDKReady = true,
            () -> isSDKReady = false
        );
    }
    
    public void monitorContent(String platform, String content) {
        if (isSDKReady) {
            ParentalAI.sendTextIncident(platform, content);
        }
    }
}

Chat Application Integration

public class ChatActivity extends AppCompatActivity {
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_chat);
        
        setupChatMonitoring();
    }
    
    private void setupChatMonitoring() {
        EditText messageInput = findViewById(R.id.message_input);
        Button sendButton = findViewById(R.id.send_button);
        
        sendButton.setOnClickListener(v -> {
            String message = messageInput.getText().toString();
            
            // Monitor content before sending
            ParentalAI.sendTextIncident("chat-app", message);
            
            // Send message normally
            sendMessage(message);
            messageInput.setText("");
        });
    }
}

Image Sharing Integration

public class PhotoShareActivity extends AppCompatActivity {
    
    private void sharePhoto(Uri imageUri) {
        try {
            // Convert image to base64
            Bitmap bitmap = MediaStore.Images.Media.getBitmap(getContentResolver(), imageUri);
            String base64Image = encodeImageToBase64(bitmap);
            
            // Monitor image content
            ParentalAI.sendImageIncident("photo-share", base64Image);
            
            // Proceed with sharing
            uploadAndShareImage(imageUri);
            
        } catch (IOException e) {
            Log.e("PhotoShare", "Error processing image", e);
        }
    }
}

Error Handling

Best Practices

public class ContentMonitor {
    
    public void monitorText(String platform, String content) {
        try {
            // Validate inputs
            if (platform == null || platform.isEmpty()) {
                Log.w("Monitor", "Platform identifier is required");
                return;
            }
            
            if (content == null || content.trim().isEmpty()) {
                Log.d("Monitor", "Skipping empty content");
                return;
            }
            
            // Monitor content
            ParentalAI.sendTextIncident(platform, content);
            
        } catch (IllegalStateException e) {
            Log.e("Monitor", "SDK not initialized", e);
            // Handle gracefully - maybe retry initialization
        } catch (Exception e) {
            Log.e("Monitor", "Unexpected error monitoring content", e);
            // Don't let monitoring errors break app functionality
        }
    }
}

Retry Logic

public class RobustContentMonitor {
    private static final int MAX_RETRIES = 3;
    
    public void monitorWithRetry(String platform, String content) {
        monitorWithRetry(platform, content, 0);
    }
    
    private void monitorWithRetry(String platform, String content, int attempt) {
        try {
            ParentalAI.sendTextIncident(platform, content);
        } catch (IllegalStateException e) {
            if (attempt < MAX_RETRIES) {
                // Wait and retry
                new Handler().postDelayed(() -> 
                    monitorWithRetry(platform, content, attempt + 1), 
                    1000 * (attempt + 1)
                );
            } else {
                Log.e("Monitor", "Failed to monitor content after " + MAX_RETRIES + " attempts");
            }
        }
    }
}

Performance Considerations

Batching Content

For high-frequency content (like typing indicators), consider batching:

public class BatchContentMonitor {
    private final List<String> pendingContent = new ArrayList<>();
    private final Handler handler = new Handler();
    private final Runnable batchProcessor = this::processBatch;
    
    public void queueContent(String platform, String content) {
        synchronized (pendingContent) {
            pendingContent.add(content);
        }
        
        // Process batch after 500ms of inactivity
        handler.removeCallbacks(batchProcessor);
        handler.postDelayed(batchProcessor, 500);
    }
    
    private void processBatch() {
        synchronized (pendingContent) {
            if (!pendingContent.isEmpty()) {
                String combinedContent = String.join(" ", pendingContent);
                ParentalAI.sendTextIncident("chat-app", combinedContent);
                pendingContent.clear();
            }
        }
    }
}

Image Optimization

private String optimizeAndEncodeImage(Bitmap original) {
    // Resize large images for better performance
    int maxSize = 1024;
    if (original.getWidth() > maxSize || original.getHeight() > maxSize) {
        float ratio = Math.min(
            (float) maxSize / original.getWidth(),
            (float) maxSize / original.getHeight()
        );
        int width = Math.round(original.getWidth() * ratio);
        int height = Math.round(original.getHeight() * ratio);
        original = Bitmap.createScaledBitmap(original, width, height, true);
    }
    
    return encodeImageToBase64(original);
}

Related Classes

• ParentalAIConfig - Configuration object for SDK initialization
• IngestionPayload - Internal data model for content incidents
• User - User account model
• TokenRequest - Authentication request model

See Also

• Getting Started Guide - Basic SDK integration
• Installation Guide - Detailed setup instructions
• Authentication Guide - Google OAuth configuration
• Text Monitoring Guide - Text content monitoring strategies
• Image Monitoring Guide - Image content monitoring strategies

---

Need help with implementation? Check our platform-specific examples or contact info@cirvia.co.