Skip to main content

Data Models Reference

This document describes the data models used throughout the Cirvia Parental SDK. These classes represent the structure of data exchanged between your app, the SDK, and Cirvia backend services.

Overview​

The SDK uses several data models:

  • User - Represents authenticated parent accounts
  • IngestionPayload - Internal model for content incident data
  • TokenRequest - Authentication request structure

Most of these models are used internally by the SDK, but understanding their structure helps with debugging and advanced integrations.

User​

Represents a parent user account in the Cirvia system.

Package​

package com.cirvia.parentalai.model;

Class Declaration​

public class User

Properties​

PropertyTypeDescription
idUUIDUnique identifier for the user account
emailStringUser's email address from Google OAuth
nameStringUser's display name from Google profile
pictureStringURL to user's profile picture

Constructor​

Default Constructor​

public User()

Used primarily for JSON deserialization by the SDK.

Parameterized Constructor​

public User(String email, String name, String picture)

Creates a new User instance (used internally during account creation).

Methods​

getId()​

public UUID getId()

Returns the unique identifier for this user account.

setId()​

public void setId(UUID id)

Sets the unique identifier (used internally by SDK).

getEmail()​

public String getEmail()

Returns the user's email address.

setEmail()​

public void setEmail(String email)

Sets the user's email address.

getName()​

public String getName()

Returns the user's display name.

setName()​

public void setName(String name)

Sets the user's display name.

getPicture()​

public String getPicture()

Returns the URL to the user's profile picture.

setPicture()​

public void setPicture(String picture)

Sets the URL to the user's profile picture.

Example JSON Structure​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "parent@example.com",
  "name": "John Smith",
  "picture": "https://lh3.googleusercontent.com/a/default-user=s96-c"
}

Usage​

The User model is primarily used internally by the SDK during authentication. You typically won't create User objects directly, but you might access user information for display purposes:

// This is handled internally by the SDK
ParentalAI.init(context, config, 
    () -> {
        // User authentication successful
        // User data is stored internally by SDK
        Log.d("Auth", "Parent account authenticated successfully");
    },
    () -> {
        Log.w("Auth", "Parent authentication failed or declined");
    }
);

IngestionPayload​

Internal model used to structure content data sent to Cirvia's moderation services.

Package​

package com.cirvia.parentalai.model;

Class Declaration​

public class IngestionPayload

Properties​

PropertyTypeDescription
userIdUUIDID of the parent user account
platformStringPlatform identifier (e.g., "roblox", "discord")
contentTypeStringType of content: "text" or "image"
rawContentStringText content (null for images)
rawImgStringBase64 image data (null for text)

Constructor​

public IngestionPayload(
    UUID userId, 
    String platform, 
    String contentType, 
    String rawContent, 
    String rawImg
)

Creates a new payload for content ingestion.

Methods​

All standard getter and setter methods are available:

  • getUserId() / setUserId(UUID userId)
  • getPlatform() / setPlatform(String platform)
  • getContentType() / setContentType(String contentType)
  • getRawContent() / setRawContent(String rawContent)
  • getRawImg() / setRawImg(String rawImg)

Example JSON Structure​

Text Content​

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "roblox",
  "contentType": "text",
  "rawContent": "Hey, want to meet up after school?",
  "rawImg": null
}

Image Content​

{
  "userId": "550e8400-e29b-41d4-a716-446655440000", 
  "platform": "instagram",
  "contentType": "image",
  "rawContent": null,
  "rawImg": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Usage​

This model is used internally when you call ParentalAI.sendTextIncident() or ParentalAI.sendImageIncident():

// When you call this:
ParentalAI.sendTextIncident("my-app", "User message here");

// SDK internally creates:
IngestionPayload payload = new IngestionPayload(
    currentUserId,
    "my-app", 
    "text",
    "User message here",
    null
);

TokenRequest​

Used for Google OAuth token exchange during authentication.

Package​

package com.cirvia.parentalai.model;

Class Declaration​

public class TokenRequest

Properties​

PropertyTypeDescription
idTokenStringGoogle OAuth ID token

Constructor​

public TokenRequest(String idToken)

Creates a new token request with the provided Google ID token.

Methods​

getIdToken()​

public String getIdToken()

Returns the Google OAuth ID token.

setIdToken()​

public void setIdToken(String idToken)

Sets the Google OAuth ID token.

Example JSON Structure​

{
  "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjdlNzA..."
}

Usage​

This model is used internally during the authentication flow:

// When ParentalAI.init() is called:
// 1. User authenticates with Google
// 2. SDK receives Google ID token
// 3. SDK creates TokenRequest and sends to Cirvia backend
TokenRequest request = new TokenRequest(googleIdToken);
// 4. Backend validates token and returns User object

Response Models​

Incident Response​

When content is processed by Cirvia's AI moderation system, it returns structured data about the analysis:

Risk Assessment​

{
  "incidentId": "123e4567-e89b-12d3-a456-426614174000",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "roblox",
  "contentType": "text",
  "rawContent": "Inappropriate message content",
  "score": 8.5,
  "tags": {
    "harassment": "true",
    "sexual": "false", 
    "violence": "false",
    "hate": "true",
    "self_harm": "false"
  },
  "createdAt": "2025-01-07T15:30:00Z"
}

Score Interpretation​

Score RangeRisk LevelParent Action
1.0 - 3.9LowLogged only
4.0 - 6.9MediumDashboard notification
7.0 - 10.0HighImmediate alert

Content Categories​

TagDescription
harassmentBullying, threats, intimidation
sexualSexual content, inappropriate advances
violenceViolent threats, graphic content
hateHate speech, discrimination
self_harmSelf-harm references, suicide ideation

Data Flow Examples​

Text Monitoring Flow​

// 1. Developer calls SDK method
ParentalAI.sendTextIncident("chat-app", "User typed message");

// 2. SDK creates IngestionPayload
IngestionPayload payload = new IngestionPayload(
    authenticatedUserId,
    "chat-app",
    "text", 
    "User typed message",
    null
);

// 3. SDK sends to Cirvia backend for analysis
// 4. AI processes content and returns risk assessment
// 5. High-risk content appears in parent dashboard

Authentication Flow​

// 1. SDK initiates Google OAuth
// 2. User authenticates and provides consent
// 3. SDK receives Google ID token
// 4. SDK creates TokenRequest
TokenRequest tokenRequest = new TokenRequest(googleIdToken);

// 5. SDK sends to Cirvia auth endpoint
// 6. Backend validates token and returns User object
User authenticatedUser = authResponse.getUser();

// 7. SDK stores user info for future requests

Working with Models​

Type Safety​

All models use appropriate Java types for type safety:

// UUID for unique identifiers
UUID userId = user.getId();

// Enums for fixed values (conceptual - actual implementation may vary)
ContentType contentType = ContentType.TEXT;
Platform platform = Platform.ROBLOX;

Null Safety​

Always check for null values when working with optional fields:

public void processIncident(IngestionPayload payload) {
    // Text content is null for images
    if (payload.getRawContent() != null) {
        processTextContent(payload.getRawContent());
    }
    
    // Image data is null for text
    if (payload.getRawImg() != null) {
        processImageContent(payload.getRawImg());
    }
}

JSON Serialization​

The SDK uses Gson for JSON serialization. All models are designed to work seamlessly with Gson's default configuration:

// Example of how SDK serializes data internally
Gson gson = new Gson();
String json = gson.toJson(ingestionPayload);

// Example JSON output:
// {"userId":"550e8400-...","platform":"roblox","contentType":"text",...}

Error Models​

API Error Response​

{
  "error": "INVALID_API_KEY",
  "message": "The provided API key is invalid or expired",
  "code": 401,
  "timestamp": "2025-01-07T15:30:00Z"
}

Validation Error Response​

{
  "error": "VALIDATION_ERROR",
  "message": "Content is required for text incidents",
  "code": 400,
  "details": {
    "field": "rawContent",
    "issue": "cannot be null or empty"
  }
}

Best Practices​

Model Validation​

public static boolean isValidPayload(IngestionPayload payload) {
    if (payload.getUserId() == null) return false;
    if (payload.getPlatform() == null || payload.getPlatform().isEmpty()) return false;
    if (payload.getContentType() == null) return false;
    
    // Validate content based on type
    if ("text".equals(payload.getContentType())) {
        return payload.getRawContent() != null && !payload.getRawContent().trim().isEmpty();
    } else if ("image".equals(payload.getContentType())) {
        return payload.getRawImg() != null && !payload.getRawImg().trim().isEmpty();
    }
    
    return false;
}

Safe Data Access​

public String getUserDisplayName(User user) {
    if (user == null) return "Unknown User";
    
    String name = user.getName();
    if (name != null && !name.trim().isEmpty()) {
        return name;
    }
    
    String email = user.getEmail();
    if (email != null && !email.trim().isEmpty()) {
        return email.split("@")[0]; // Use email prefix as fallback
    }
    
    return "Unknown User";
}

Understanding the data models helps with debugging and advanced integrations. For most use cases, you'll primarily interact with the high-level ParentalAI methods rather than these models directly.