@trustarc/react-cookie-consent-manager/readme.md

React components to integrate TrustArc Cookie Consent Manager into React Frameworks

# TrustArc React Cookie Consent

Welcome to the **TrustArc React Cookie Consent Manager** component! This library is designed to help clients using React frameworks integrate TrustArc Cookie Consent banners and related components seamlessly, while avoiding hydration issues during unmounts.

This is a **beta project**, and we are actively improving it based on your feedback. Please feel free to share your thoughts and suggestions!

---

## Installation

To install the package, use the following command:

```bash
npm install @trustarc/react-cookie-consent-manager
```

---

## Building the Component

Before using or publishing the package, ensure it's built properly:

```sh
npm install  # Install dependencies
npm run build  # Generate the production-ready bundle
```

---

## Tested Frameworks

This library has been tested with the following frameworks:

- **Next.js**
- **Gatsby**
- **Vite (React)**
- **Preact**
- **React.js**

If you encounter issues with other frameworks, please let us know!

---

## How It Works

This component provides a set of TrustArc-related components that can be easily integrated into your React application. It ensures that TrustArc scripts and banners are properly mounted and unmounted without causing hydration issues.

### Key Features:
- Dynamically injects TrustArc scripts into your application.
- Provides reusable components for cookie consent banners, cookie preferences links, and IRM links.
- Designed to minimize unnecessary mounts/unmounts by recommending usage in a layout component.

---

## Example Usage

We recommend adding TrustArc components in a layout to avoid unnecessary mount/unmount cycles. Below is an example of how to use the library in a `Layout` component:

```tsx
import React, { CSSProperties } from "react";
import { Link } from "react-router-dom";
import { createTrustArcComponents } from "@trustarc/react-cookie-consent-manager";

interface LayoutProps {
  children: React.ReactNode;
}

const Layout: React.FC<LayoutProps> = ({ children }) => {
  
  const {
    TrustArcScript,
    TrustArcConsentBanner,
    TrustArcCookiePreferencesLink,
    TrustArcIRMLink,
  // Placeholder for additional TrustArc components or configurations
  // Update this section with any custom TrustArc components or options as needed
  } = createTrustArcComponents("<YOURINSTANCEID>", {
    cookiePreferencesContainer: "teconsent",
    debug: true,
  });

  return (
    <div style={styles.container}>
      {/* Header */}
      <TrustArcScript />
      <TrustArcConsentBanner />
      <header style={styles.header}>
        <h1>TrustArc Demo</h1>
        <nav>
          <Link to="/" style={styles.link}>Home</Link>
          <Link to="/about" style={styles.link}>About</Link>
        </nav>
      </header>

      {/* Page Content */}
      <main style={styles.content}>{children}</main>

      {/* Footer with Cookie Preferences */}
      <footer style={styles.footer}>
        <TrustArcCookiePreferencesLink />
        <TrustArcIRMLink />
        <p>© 2025 TrustArc. All rights reserved.</p>
      </footer>
    </div>
  );
};

const styles: { [key: string]: CSSProperties } = {
  container: { display: "flex", flexDirection: "column", minHeight: "100vh" },
  header: { background: "#0073e6", padding: "15px", textAlign: "center", color: "white" },
  content: { flex: 1, padding: "20px", textAlign: "center" },
  footer: { background: "#f1f1f1", padding: "15px", textAlign: "center", marginTop: "auto" },
  link: { margin: "0 10px", color: "white", textDecoration: "none", fontSize: "18px" },
};

export default Layout;
```

---

## Available Parameters

Here is a list of all parameters available in the `TrustArcOptions` interface:

| Parameter                  | Type      | Description                                                                 |
|----------------------------|-----------|-----------------------------------------------------------------------------|
| `cookiePreferencesContainer` | `string` | The ID of the container where the cookie preferences link will be injected. |
| `showCookiePreferencesAsButton` | `boolean` | Displays the "Cookie Preferences" link as a button if set to `true`.        |
| `irmContainer`             | `string`  | The ID of the container where the IRM link will be injected.                |
| `js`                       | `string`  | Specifies the JavaScript type for the TrustArc script (e.g., `nj`).         |
| `noticeType`               | `string`  | Defines the type of notice to display (e.g., `bb` for banner).              |
| `countryCodeorIP`          | `string`  | Overrides dynamic IP detection with a country code or IP address.           |
| `state`                    | `string`  | Pre-configures state-specific consent behavior (e.g., `ca` for California). |
| `language`                 | `string`  | Overrides browser language detection with a specific language code.         |
| `pcookie`                  | `boolean` | Enables or disables persistent cookies.                                     |
| `behavior`                 | `string`  | Forces specific behavior for the consent manager (e.g., `expressed`).       |
| `privacyPolicyLink`        | `string`  | Overrides the default privacy policy link in the Consent Manager.           |
| `ccmVersion`               | `string`  | Specifies the version of the TrustArc Consent Manager (e.g., `Pro`).        |
| `pn`                       | `string`  | Loads a specific page in the Consent Manager as the first screen.           |
| `onclose`                  | `boolean` | Allows closing the Consent Manager by clicking outside the frame.           |
| `ostype`                   | `boolean` | Uses radio buttons instead of sliders for the consent banner.               |
| `fade`                     | `number`  | Time in milliseconds before the banner fades.                               |
| `px`                       | `number`  | Number of pixels the user must scroll before the banner collapses.          |
| `cookiePolicyLink`         | `string`  | Encoded URL for the cookie policy displayed as a button in the banner.      |
| `privacypolicylink`        | `string`  | Overrides the privacy policy link in the Consent Manager.                   |
| `loadScriptAsync`          | `boolean` | Loads the TrustArc script asynchronously if set to `true`.                  |
| `debug`                    | `boolean` | Enables debug logging for troubleshooting.                                  |

## Disclaimer

This library is provided as-is, and it is the **client's responsibility** to ensure proper integration and compliance with their specific requirements. While we strive to make this library robust and reliable, we recommend thorough testing in your environment before deploying it to production.

---

## Feedback

We value your feedback! As this is a beta project, we are continuously improving it. Please reach out to our support team or your Technical Account Manager to share your thoughts, suggestions, or report any issues.

Thank you for using **TrustArc React Cookie Consent**!