npm package: @homekynd/hk-embed-sdk
Description: A lightweight SDK for embedding Homekynd applications into your website with secure authentication and seamless integration.
Latest version: 0.1.1

A lightweight SDK for embedding Homekynd applications into your website with secure authentication and seamless integration.

---

<p align="center">
<img width="160" height="160" alt="package-logo" src="https://storage.googleapis.com/hk-prod-main/hk-sdk-logo.png" />
</p>

<h1 align="center">HKEmbed SDK</h1>

## Installation

Contact your Homekynd representative to get access credentials, then choose one of the installation methods below:

### NPM Package

```bash
npm install @homekynd/hk-embed-sdk
```

### CDN

```html
<script src="https://storage.googleapis.com/hk-prod-main/sdk/hk-sdk.cdn.x.x.x.umd.js"></script>
```

Replace `x.x.x` with the desired version number (e.g., `1.0.0`, `2.1.3`).

> [!IMPORTANT]  
> This package requires authentication credentials provided by Homekynd. Contact support@homekynd.com for access.

## Quick Start

### For React Applications

```tsx
import React from "react";
import { HKReactEmbed } from "@homekynd/hk-embed-sdk";

function MyComponent() {
  return (
    <HKReactEmbed
      clientId="your-client-id"
      apiKey="your-api-key"
      width="100%"
      height="600px"
      style={{ border: "1px solid #ddd", borderRadius: "8px" }}
    />
  );
}
```

### Available Handlers

| Function                    | Type                                                      |
| --------------------------- | --------------------------------------------------------- |
| `addModel(modelId: string)` | Adds a model in the iframe canvas by passing the model ID |
| `getDeviceId()`             | Provides the device unique identification (uuid format)   |

### Configuration Options React

| Option     | Type                             | Required | Default        | Description                               |
| ---------- | -------------------------------- | -------- | -------------- | ----------------------------------------- |
| `clientId` | `string`                         | ✅ Yes   | -              | Your Homekynd client ID                   |
| `apiKey`   | `string`                         | ✅ Yes   | -              | Your Homekynd API key                     |
| `width`    | `string \| number`               | No       | `"100%"`       | Embed width (e.g., "500px", "100%", 500)  |
| `height`   | `string \| number`               | No       | `"100%"`       | Embed height (e.g., "400px", "50vh", 400) |
| `path`     | `"designTool" \| "configurator"` | No       | `"designTool"` | Initial page to load                      |
| `style`    | `React.CSSProperties`            | No       | -              | Custom styles                             |

### For Vanilla JavaScript (NPM)

```html
<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <div id="homekynd-embed" style="width: 100%; height: 600px;"></div>

    <script type="module">
      import { HKEmbed } from "@homekynd/hk-embed-sdk";

      new HKEmbed({
        container: document.getElementById("homekynd-embed"),
        clientId: "your-client-id",
        apiKey: "your-api-key",
        width: "100%",
        height: "600px",
      });
    </script>
  </body>
</html>
```

### For Vanilla JavaScript (CDN)

```html
<!DOCTYPE html>
<html>
  <head>
    <script src="https://storage.googleapis.com/hk-prod-main/sdk/hk-sdk.cdn.x.x.x.umd.js"></script>
  </head>

  <body>
    <div id="homekynd-embed"></div>
    <script>
      new HkEmbed({
        container: document.getElementById("homekynd-embed"),
        clientId: "your-client-id",
        apiKey: "your-api-key",
        width: "100%",
        height: "600px",
      });
    </script>
  </body>
</html>
```

### Configuration Options Vanilla

| Option      | Type                             | Required | Default        | Description                               |
| ----------- | -------------------------------- | -------- | -------------- | ----------------------------------------- |
| `clientId`  | `string`                         | ✅ Yes   | -              | Your Homekynd client ID                   |
| `apiKey`    | `string`                         | ✅ Yes   | -              | Your Homekynd API key                     |
| `container` | `HTMLElement`                    | ✅ Yes   | -              | Container element                         |
| `width`     | `string \| number`               | No       | `"100%"`       | Embed width (e.g., "500px", "100%", 500)  |
| `height`    | `string \| number`               | No       | `"100%"`       | Embed height (e.g., "400px", "50vh", 400) |
| `path`      | `"designTool" \| "configurator"` | No       | `"designTool"` | Initial page to load                      |

## Common Examples

### Full Width Embed

```tsx
<HKReactEmbed
  clientId="your-client-id"
  apiKey="your-api-key"
  width="100%"
  height="500px"
/>
```

### Fixed Size Embed

```tsx
<HKReactEmbed
  clientId="your-client-id"
  apiKey="your-api-key"
  width={800}
  height={600}
/>
```

### Responsive Embed

```tsx
<HKReactEmbed
  clientId="your-client-id"
  apiKey="your-api-key"
  width="100%"
  height="70vh"
  style={{
    minHeight: "400px",
    maxWidth: "1200px",
    margin: "0 auto",
  }}
/>
```

## Troubleshooting

### The embed doesn't load

- ✅ Check that your `clientId` and `apiKey` are correct
- ✅ Verify your credentials are active (contact support if needed)
- ✅ Ensure the container element exists before initializing

### The embed appears but shows an error

- ✅ Your credentials may be expired or inactive
- ✅ Check the browser console for specific error messages
- ✅ Contact Homekynd support with the error details

### Styling issues

- ✅ Make sure the container has explicit width/height
- ✅ Check for CSS conflicts in your application
- ✅ Use the `style` prop (React) for custom styling

## Need Help?

- 📧 **Support**: support@homekynd.com
- 📖 **Documentation**: Additional resources available in your client portal

## License

This software is proprietary to Homekynd, Inc. Usage is restricted to authorized clients and partners under the terms of your service agreement with Homekynd.

**© 2025 Homekynd, Inc. All rights reserved.**