# finderCONNECT SDK Integration

## Introduction

The Intelibly finderconnect-sdk is a powerful upgrade designed for seamless integration into any
website. This SDK introduces enhanced compatibility with external analytics platforms and user
metrics tracking. It also simplifies installation through a new custom HTML element, enabling
better styling and deeper insights into user interactions.

After installing the SDK, review
[Best practices and recommendations](/finderconnect/best-practices) for guidance on copy and links
to place near the map.

---

## Add finderconnect-sdk to Your Website

The finderconnect-sdk introduces a new installation method using a **custom HTML element** called
`<finderconnect>`. This replaces the static iframe and enables dynamic configuration and analytics
integration.

### Installation Steps

1. **Embed the script** before the closing `</body>` tag of your webpage. Include your partner ID
   in the script URL:

   ```html icon=xml
   <script src="https://app.intelibly.com/finderconnect.js?partner_id=YOUR_PARTNER_ID"></script>
   ```

2. **Add the custom element** where you want the map to appear:

   ```html icon=xml
   <finderconnect
     partner-id="YOUR_PARTNER_ID"
     width="100%"
     height="80vh"
     style="border-radius: 8px;">
   </finderconnect>
   ```

---

## Integration Notes

### SDK Requirement

Ensure the finderconnect-sdk is loaded on your page. Include your partner ID in the script URL:

```html icon=xml
<script src="https://app.intelibly.com/finderconnect.js?partner_id=YOUR_PARTNER_ID"></script>
```

**Note:** The partner ID can be specified either in the script URL or as a `partner-id` attribute on
the `<finderconnect>` element. If both are provided, the element attribute takes precedence.

### Customization

The `<finderconnect>` element supports customization through CSS properties in the `style`
attribute. You can customize styling properties:

```html icon=xml
<finderconnect
  partner-id="YOUR_PARTNER_ID"
  width="100%"
  height="80vh"
  style="border-radius: 8px;">
</finderconnect>
```

#### Supported CSS Properties

You can also apply standard CSS properties like `border-radius` directly in the `style` attribute to
customize the appearance of the widget.

### Geolocation Support

The finderconnect-sdk can use the browser's geolocation API to provide location-based search
functionality, allowing users to find nearby locations based on their current position. To enable
this feature, you need to configure your website's Permissions-Policy header to allow geolocation
access for embedded elements.

#### Why Enable Geolocation?

When geolocation is enabled, users can:

- Automatically search for locations near their current position
- Get more accurate distance calculations
- Experience a more personalized search experience

#### Implementation

To enable geolocation support, add the `geolocation` permission to your website's
Permissions-Policy HTTP header. This allows the `<finderconnect>` element to request location access
from users.

**Example Permissions-Policy header:**

```
Permissions-Policy: geolocation=(self "https://app.intelibly.com")
```

This configuration allows geolocation access for your own domain (`self`) and the finderconnect-sdk
domain.

**Note:** Users will still be prompted by their browser to grant location permission when the SDK
requests it. This is a standard browser security feature.

For more detailed information about configuring Permissions-Policy headers and geolocation
permissions, refer to the
[MDN documentation on Permissions-Policy for geolocation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy/geolocation#with_an_iframe_element).

### Security

If your website uses Content Security Policy (CSP) headers, you'll need to update your CSP
configuration to allow the finderconnect-sdk to load and function properly. The SDK requires
permissions for script sources and frame sources.

#### Content Security Policy Configuration

Add the following domains to your Content Security Policy headers:

**Script Source (`script-src`):** The SDK script needs to be loaded from Intelibly's CDN. Add the
following to your `script-src` directive:

```
script-src 'self' https://app.intelibly.com;
```

**Frame Source (`frame-src` or `child-src`):** If the SDK uses iframes internally, you'll need to
allow frames from Intelibly domains. Add the following to your `frame-src` or `child-src` directive:

```
frame-src 'self' https://app.intelibly.com;
```

or

```
child-src 'self' https://app.intelibly.com;
```

**Connect Source (`connect-src`):** If the SDK makes API calls, you may also need to allow
connections to Intelibly domains:

```
connect-src 'self' https://app.intelibly.com;
```

#### Complete CSP Example

Here's an example of a complete Content Security Policy header that includes the necessary
permissions for finderconnect-sdk:

```
Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://app.intelibly.com;
  frame-src 'self' https://app.intelibly.com;
  connect-src 'self' https://app.intelibly.com;
```

**Note:** Adjust these directives according to your existing CSP policy. If you're using a nonce or
hash-based CSP, you may need to include the SDK script using those methods instead.

#### Testing Your CSP

After updating your CSP headers, test the integration to ensure:

- The SDK script loads without console errors
- The `<finderconnect>` element renders correctly
- All SDK functionality works as expected

If you encounter CSP violations, check your browser's console for specific error messages and adjust
your policy accordingly.