# Integration

## 1. Put the package in your project

Example:

```text
/public_html/fingerprint_guard/
```

Make sure PHP can write to:

```text
fingerprint_guard/storage/
```

## 2. Set secret

Open:

```text
fingerprint_guard/lib/FingerprintGuard.php
```

Replace `APP_SECRET` with:

```bash
php -r "echo bin2hex(random_bytes(32)), PHP_EOL;"
```

## 3. Test built-in signup/login

For a standalone cPanel test, use:

```text
/fingerprint_guard/public/signup.php
/fingerprint_guard/public/login.php
/fingerprint_guard/public/dashboard.php
/fingerprint_guard/public/my-browser-security.php
```

The demo signup stores users in local JSON files under `storage/users/` using PHP `password_hash()`.

## 4. Add widget

```html
<script src="/fingerprint_guard/public/fp-widget.js" defer></script>
<script>
window.addEventListener('load', function () {
  window.FingerprintGuard.collect({
    endpoint: '/fingerprint_guard/public/collect.php',
    nonceEndpoint: '/fingerprint_guard/public/nonce.php',
    mode: 'strict',
    debug: false
  }).then(function (r) {
    if (r.risk_score >= 75) {
      // block, manual review, captcha, OTP, or custom security flow
    } else if (r.risk_score >= 45) {
      // step-up verification
    }
  });
});
</script>
```

## 5. Link to logged-in account

After your normal login verification succeeds:

```php
session_start();
$_SESSION['user_id'] = $yourUserId;

require_once __DIR__ . '/fingerprint_guard/lib/FingerprintGuard.php';
$guard = new FingerprintGuard();
$linkResult = $guard->linkAccount((string)$_SESSION['user_id']);
```

## 6. Read current browser risk

```php
require_once __DIR__ . '/fingerprint_guard/lib/FingerprintGuard.php';
$guard = new FingerprintGuard();
$risk = $guard->getLatestRiskForBrowser();
```

Or open:

```text
/fingerprint_guard/public/risk-report.php
```

## 7. Read account browser report

```php
require_once __DIR__ . '/fingerprint_guard/lib/FingerprintGuard.php';
$guard = new FingerprintGuard();
$report = $guard->getAccountBrowserReport((string)$_SESSION['user_id'], false);
```

Endpoint:

```text
/fingerprint_guard/public/account-report.php
```

Include raw latest payload:

```text
/fingerprint_guard/public/account-report.php?raw=1
```

## 8. Storage

Every POST to `collect.php` creates or appends:

```text
storage/observations/{browser_id}.jsonl
```

The raw client payload is stored in each line as:

```json
"raw_payload": { ... }
```

The backend also stores:

```json
"payload_hash": "...",
"stable_hash": "...",
"volatile_hash": "...",
"mismatches": [ ... ],
"raw_mismatches": [ ... ],
"signals": [ ... ],
"risk_score": 0
```