Skip to main content

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.

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:

    <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:

    <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:

<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:

<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.

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.