@dataunlocker/defender-angular/readme.md

DataUnlocker Defender for Angular applications.

# @dataunlocker/defender-angular

Angular integration for [DataUnlocker Defender](https://docs.dataunlocker.com/setup/defender). This package provides a standalone component to protect your Angular application from content blockers using [DataUnlocker](https://www.dataunlocker.com).

## Installation

**Before installing** this package, you need to set up the `DATAUNLOCKER_ID` environment variable.

### Setting up DATAUNLOCKER_ID

You can set the environment variable in one of the following ways:

#### Option 1: Using .npmrc file

Create a `.npmrc` file in your project root:

```
DATAUNLOCKER_ID=your_dataunlocker_id_here
```

#### Option 2: Using environment variable

Set the environment variable before installing the package:

```bash
# For Unix/Linux/macOS
export DATAUNLOCKER_ID=your_dataunlocker_id_here

# For Windows (Command Prompt)
set DATAUNLOCKER_ID=your_dataunlocker_id_here

# For Windows (PowerShell)
$env:DATAUNLOCKER_ID="your_dataunlocker_id_here"
```

You can also provide DATAUNLOCKER_ID in your deployment pipeline or build cloud environment.

### Installing the library

After setting up the environment variable, install the library:

```bash
npm install @dataunlocker/defender-angular
```

## Usage

### 1. Import the Component

Import `DefenderComponent` in your root layout:

```typescript
import { DefenderComponent } from "@dataunlocker/defender-angular";

@Component({
  imports: [DefenderComponent],
  // ...
})
export class AppComponent {}
```

### 2. Wrap your app with Defender

Add `<defender>` as a top-level wrapper component on your app.

```xml
<defender>
  <!-- Your protected content goes here -->
  <div>This is your web application code</div>
</defender>
```

Defender slightly changes how your app is rendered, and introduces an extra `<div>` around your app's content.
You can style this `<div>` any way you want.

You can also listen to `loaded` and `errored` events of Defender, either with `@dataunlocker/defender-angular` binding or from the base package `@dataunlocker/defender`.
You can init your app or tracking code on the `loaded` event, but mind that placing code in DataUnlocker's Secure Enclave gives you a better protection against blockers.

```xml
<!-- (loaded) accepts data returned by Secure Enclave, (errored) accepts error code -->
<defender
  (loaded)="onLoad($event)"
  (errored)="onError($event)">
  ...
</defender>
```

## Examples

### With Navigation

```html
<defender>
  <nav>
    <!-- Navigation content -->
  </nav>
  <main>
    <router-outlet></router-outlet>
  </main>
</defender>
```

## Support

For issues and feature requests, please feel free to open the issue at [@dataunlocker/defender-angular](https://github.com/dataunlocker/defender-angular) or contact DataUnlocker support.