# Janus SDK - Agent Guidelines

## Project Overview

Janus SDK is a multi-platform privacy consent management SDK for mobile applications. It integrates with Fides/FidesPlus backend APIs and FidesJS for WebView consent synchronization.

**Platforms:**
- Android (Kotlin, API 21+)
- iOS (Swift, iOS 13.0+)
- Flutter (Dart wrapper around native SDKs)

## Directory Structure

```
janus-sdk/
├── Android/           # Android SDK (Kotlin)
│   ├── sdk/           # Core SDK library
│   └── janus-sdk-android/Example/  # Example app
├── iOS/               # iOS SDK (Swift)
│   ├── JanusSDK/      # Core SDK source
│   ├── JanusSDKTests/ # Unit tests
│   └── janus-sdk-ios/Example/  # Example app
├── Flutter/           # Flutter plugin
│   ├── janus_sdk_flutter/  # Plugin source
│   └── janus_demo/    # Demo app
└── Shared/            # Cross-platform resources
    ├── JavaScript/    # JS bridge code (tcfWebView.js, bridge.js, etc.)
    └── PrivacyExperienceMockJSON/  # Test data
```

---

## Android Development

### Prerequisites
- JDK 17 (install with `brew install openjdk@17`)
- Android Studio

### Building the SDK

```bash
cd clients/janus-sdk/Android

# Build release version (copies AAR to example app)
./gradlew buildSdk

# Build debug version (for stepping through code)
./gradlew buildDebugSdk
```

### Running Tests

```bash
# Run all unit tests
./gradlew runTests

# Run with code coverage
./gradlew runTestsWithCoverage

# Run specific test variant
./gradlew :sdk:testDebugUnitTest
./gradlew :sdk:testReleaseUnitTest
```

Test reports: `sdk/build/reports/tests/`
Coverage reports: `sdk/build/reports/jacoco/jacocoTestReport/html/index.html`

### Running the Example App

1. Build SDK first: `./gradlew buildSdk`
2. Build and install example app:
```bash
cd janus-sdk-android/Example && ./gradlew installDebug
```
3. Launch via adb:
```bash
~/Library/Android/sdk/platform-tools/adb shell am start -n com.ethyca.janussdk.android.example/.MainActivity
```

**Useful adb commands:**
```bash
# List connected devices
~/Library/Android/sdk/platform-tools/adb devices

# View logs (Janus SDK tag)
~/Library/Android/sdk/platform-tools/adb logcat -s JanusSDK

# Uninstall app
~/Library/Android/sdk/platform-tools/adb uninstall com.ethyca.janussdk.android.example
```

### Version Management

```bash
./gradlew incrementPatchVersion   # 1.0.0 -> 1.0.1
./gradlew incrementMinorVersion   # 1.0.0 -> 1.1.0
./gradlew incrementMajorVersion   # 1.0.0 -> 2.0.0
./gradlew setVersion -Pversion=1.2.3
```

---

## iOS Development

### Building the Framework

```bash
cd clients/janus-sdk/iOS

# Build release XCFramework
./build_xcframework.sh

# Build debug version
./build_xcframework.sh --debug
```

### Running Tests

```bash
# Run tests via script
./run_tests.sh

# Or in Xcode: Product > Test (⌘U)
```

Test results: `./test-results/` directory

### Running the Example App

1. Build framework first: `./build_xcframework.sh`
2. Open `janus-sdk-ios/Example/JanusExample.xcodeproj` in Xcode
3. Run the app (⌘R)

---

## Shared JavaScript (TCF WebView)

The `Shared/JavaScript/` directory contains JavaScript code injected into WebViews for TCF consent experiences:

- `tcfWebView.js` - TCF-specific styling and ready detection
- `bridge.js` - Native bridge interface
- `consent.js` - Consent handling logic
- `messaging.js` - Message passing between native and web

**Important:** Changes to these files affect both iOS and Android since both platforms inject the same scripts.

### WebView Bidirectional Sync & Loop Prevention

Consent flows bidirectionally between native and WebView. Loop prevention uses two layers:

1. **Source exclusion** — `WebViewManager.propagateConsentToOtherWebViews(sourceWebView:)` skips the originating WebView. Pass `null`/`nil` for programmatic paths (e.g. `setConsent()`).
2. **FidesJS idempotency** — FidesJS does not re-fire `FidesUpdated` when incoming values are unchanged.

See each platform's Implementation Guide (WebView Integration section) for the full explanation.

---

## Local Log Monitoring (Logdy)

For real-time log viewing during development:

```bash
# Install
brew install logdy

# Run (example apps send logs here)
logdy --no-analytics -p 8181 --api-key foobar

# View at http://localhost:8181
```

---

## Publishing

```bash
# From janus-sdk root directory

# Dry run first
./publish.sh --android --dry-run
./publish.sh --ios --dry-run

# Then publish (commits and pushes to repos)
./publish.sh --android
./publish.sh --ios
```

---

## TCF WebView Development

When working on TCF consent experience rendering:

1. **CSS injection** happens in `Shared/JavaScript/tcfWebView.js` via `injectTCFStyles()`
2. **FidesJS styles** come from the fides repo: `clients/fides-js/src/components/fides.css`
3. **embedded-consent.html** is served from Fides Privacy Center
4. The SDK uses `fides_embed=true` mode, which has different CSS behavior than standard overlay mode

### Key FidesJS CSS behaviors in embedded mode:
- Close button is hidden (`.fides-embedded .fides-close-button { display: none }`)
- Sticky footer is disabled (`.fides-modal-footer { position: inherit }`)
- No fixed positioning for banner

To override these, inject CSS via `tcfWebView.js`.

---

## Testing with Mock Data

```bash
cd Shared/PrivacyExperienceMockJSON
./download.sh <host> <region> [property_id]

# Examples:
./download.sh privacy.ethyca.com de
./download.sh privacy.ethyca.com us_ca FDS-ABC123
```

