> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useinvent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Drupal

> Add your Invent assistant to Drupal sites

## Overview

Add your Invent AI assistant to any Drupal website with a floating bubble. Perfect for enterprise websites, government sites, and large-scale content platforms.

## Installation

### Method 1: Using Block System (Recommended)

<Steps>
  <Step title="Create Custom Block">
    Navigate to **Structure** → **Block layout** → **Custom block library** → **Add custom block**
  </Step>

  <Step title="Choose Full HTML Format">
    * Give your block a description (e.g., "Invent Assistant")
    * Set **Text format** to **Full HTML**
    * Switch to **Source** mode in the editor
  </Step>

  <Step title="Add the Code">
    Paste this code:

    ```html theme={"system"}
    <invent-assistant assistant-id="YOUR_ASSISTANT_ID" />
    <script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>
    ```

    Replace `YOUR_ASSISTANT_ID` with your actual assistant ID.
  </Step>

  <Step title="Save and Place Block">
    Save the block, then place it in a region (usually **Footer** or **Page bottom**)
  </Step>

  <Step title="Configure Visibility">
    Configure block visibility settings if needed (all pages, specific pages, etc.)
  </Step>
</Steps>

### Method 2: Theme Template

Add directly to your theme's template files:

```php theme={"system"}
{# in your theme's html.html.twig or page.html.twig #}
<invent-assistant assistant-id="YOUR_ASSISTANT_ID" />
<script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>
```

### Method 3: Using a Module

Create a custom module or use an existing one:

```php theme={"system"}
<?php
// invent_assistant.module

/**
 * Implements hook_page_attachments().
 */
function invent_assistant_page_attachments(array &$attachments) {
  $attachments['#attached']['html_head'][] = [
    [
      '#type' => 'html_tag',
      '#tag' => 'invent-assistant',
      '#attributes' => [
        'assistant-id' => 'YOUR_ASSISTANT_ID',
      ],
    ],
    'invent_assistant',
  ];

  $attachments['#attached']['html_head'][] = [
    [
      '#type' => 'html_tag',
      '#tag' => 'script',
      '#attributes' => [
        'src' => 'https://www.useinvent.com/embed.js',
        'async' => TRUE,
        'defer' => TRUE,
      ],
    ],
    'invent_assistant_script',
  ];
}
```

## Customization

### Match Your Drupal Theme

```html theme={"system"}
<invent-assistant
  assistant-id="YOUR_ASSISTANT_ID"
  theme-appearance="auto"
  theme-button-background-color="#0678BE"
  theme-button-color="#FFFFFF"
/>
<script type="text/javascript" src="https://www.useinvent.com/embed.js" async defer></script>
```

### Conditional Display by Content Type

Using block visibility settings:

1. Edit your Invent Assistant block
2. Go to **Visibility** tab
3. Add conditions for **Content types**, **Pages**, or **Roles**

Or in a custom module:

```php theme={"system"}
function invent_assistant_page_attachments(array &$attachments) {
  $node = \Drupal::routeMatch()->getParameter('node');

  // Only show on article nodes
  if ($node && $node->getType() == 'article') {
    // Add assistant code
  }
}
```

## User Authentication

<Warning>
  **Security Requirement:** When using any `user-*` attributes (`user-id`, `user-name`, `user-avatar`), you **must** also provide `user-hash`. Both `user-id` and `user-hash` must be provided together, or neither should be provided. The `user-hash` must be generated on your backend using HMAC-SHA256 with your assistant's secret key. Never expose the secret key to the client.
</Warning>

Pass Drupal user information to your assistant for personalized experiences:

```php theme={"system"}
<?php
// In your theme or custom module

function invent_assistant_page_attachments(array &$attachments) {
  $current_user = \Drupal::currentUser();

  if ($current_user->isAuthenticated()) {
    $secret_key = \Drupal::config('invent_assistant.settings')->get('secret_key');
    $user_id = (string) $current_user->id();
    $user_name = $current_user->getDisplayName();
    $user_hash = hash_hmac('sha256', $user_id, $secret_key);

    $attachments['#attached']['html_head'][] = [
      [
        '#type' => 'html_tag',
        '#tag' => 'invent-assistant',
        '#attributes' => [
          'assistant-id' => 'YOUR_ASSISTANT_ID',
          'user-id' => $user_id,
          'user-name' => $user_name,
          'user-hash' => $user_hash,
        ],
      ],
      'invent_assistant',
    ];
  }
}
```

## Drupal Commerce Integration

For e-commerce sites:

* Product support and questions
* Order tracking assistance
* Shipping information
* Returns and refunds help

## Tips for Drupal

<CardGroup cols={2}>
  <Card title="Drupal 9 & 10" icon="check">
    Fully compatible with modern Drupal versions
  </Card>

  <Card title="Multilingual" icon="language">
    Works with Drupal's multilingual system
  </Card>

  <Card title="Paragraphs" icon="align-left">
    Can be added as a paragraph type
  </Card>

  <Card title="Layout Builder" icon="table-cells">
    Compatible with Layout Builder
  </Card>
</CardGroup>

## Advanced Configuration

### Add to Specific Regions

In your theme:

```yaml theme={"system"}
# your_theme.info.yml
regions:
  header: Header
  content: Content
  sidebar: Sidebar
  footer: Footer
  invent_assistant: 'Invent Assistant'
```

### Cache Considerations

Clear Drupal caches after adding the assistant:

```bash theme={"system"}
drush cr
# or
drush cache-rebuild
```

### Performance Optimization

Use async/defer attributes (already included) and consider using Drupal's aggregation:

```php theme={"system"}
$attachments['#attached']['library'][] = 'your_module/invent-assistant';
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bubble not appearing">
    **Solutions:**

    * Clear all Drupal caches (Configuration → Performance → Clear all caches)
    * Verify text format is set to "Full HTML"
    * Check block placement and region
    * Ensure block is enabled and visible
  </Accordion>

  <Accordion title="Conflicts with other modules">
    **Solutions:**

    * Check for JavaScript conflicts in browser console
    * Adjust block weight/order
    * Test with minimal theme/modules
  </Accordion>

  <Accordion title="Not showing for anonymous users">
    **Solutions:**

    * Check block visibility permissions
    * Verify "Anonymous user" role can see the block
    * Check cache settings for anonymous users
  </Accordion>
</AccordionGroup>

## Drupal Version Compatibility

<Note>
  * **Drupal 7:** Use Block system or theme templates
  * **Drupal 8/9/10:** All methods supported
  * **Drupal 11:** Fully compatible (when released)
</Note>

## Popular Drupal Distributions

Works with:

* **Acquia Lightning**
* **OpenSocial**
* **Commerce Kickstart**
* **Panopoly**
* **Thunder**
* And all other Drupal distributions