npm package: @local-logic/sdks-js
Description: Local Logic SDKs JS provides access to the next generation of Local Logic web SDKs.
Author: Local Logic
Latest version: 1.24.18

# Local Logic SDKs JS (Beta)

Local Logic SDKs JS provides access to the next generation of Local Logic web SDKs.

## Getting started

### Installation

First, install with `yarn`, `pnpm`, or `npm`:

```
yarn add @local-logic/sdks-js
```

```
pnpm add @local-logic/sdks-js
```

```
npm i --save @local-logic/sdks-js
```

The script is also available in `umd` and `es` format from the Local Logic CDN:
`https://sdk.locallogic.co/sdks-js/<VERSION>/index.<FORMAT>.js`

### Usage

You can now import `LocalLogicSDK`:

```js
import LocalLogicSDK from "@local-logic/sdks-js";

const ll = LocalLogicSDK("<API_KEY>");
```

> ℹ️ Your `API_KEY` should be provided to you by a Local Logic team member.

With the instance of `LocalLogicSDK`, you are now free to create new widgets:

```js
// Code from previous step
// ...

/**
 * Create a container HTMLElement
 */
const container = document.createElement("div");
container.style.cssText = `
  height: 100vh;
  width: 100vw;
  display: flex;
`;
document.body.appendChild(container);

// Render Local Content into the container
ll.create("local-content", container, {
  lat: 45.52859,
  lng: -73.58785,
  marker: {
    lat: 45.52859,
    lng: -73.58785,
  },
});
```

## Browser support

The SDKs are configured with `Browserslist` and `@vitejs/plugin-legacy` to support [these browsers](https://browserslist.dev/?q=PiAwLjIlLCBub3QgZGVhZCwgbm90IElFIDEx).

The SDKs will only serve polyfilled chunks only in legacy browsers without native ESM support. This keeps bundle sizes small for modern browsers.

## API

### `LocalLogicSDK`

`LocalLogicSDK` instance provides global config options and methods.

#### Options

`LocalLogicSDK(apiKey, options)`

| Name                 | Required | Type            | Default | Description                                                                                                |
| -------------------- | -------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `apiKey`             | `true`   | `string`        |         | ApiKey required for making requests to the Local Logic API.                                                |
| `options.appearance` | `false`  | `AppearanceAPI` |         | The `appearance` option provides theme and variable support customizing the look and feel of your widgets. |
| `options.locale`     | `false`  | `"en" \| "fr"`  | `"en"`  | The `locale` option specifies the language of the scores and the UI interface.                             |

### `localLogicSDK.create`

The `create` method is used to render new widget instances.

#### Options

`localLogicSDK.create(sdkType, container, options, renderOptions)`

| Name                 | Required | Type                                | Default | Description                                                                           |
| -------------------- | -------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `sdkType`            | `true`   | `"local-content" \| "demographics"` |         | The SDK you would like to create.                                                     |
| `container`          | `true`   | `HTMLElement`                       |         | The element to render in to.                                                          |
| `options`            | `true`   | `object`                            |         | Options required for te specified `sdkType`. Options for each SDK are detailed below. |
| `options.lat`        | `true`   | `number`                            |         | Initial viewport latitude.                                                            |
| `options.lng`        | `true`   | `number`                            |         | Initial viewport longitude.                                                           |
| `renderOptions.lazy` | `false`  | `number`                            | `true`  | If `true`, the SDK will only load content when it scrolls into the viewport.          |

##### "local-content" specific options

| Name                  | Required | Type                                                    | Default  | Description                                                                                                                                                                        |
| --------------------- | -------- | ------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `zoom`                | `false`  | `number`                                                | `16`     | Initial viewport zoom.                                                                                                                                                             |
| `pitch`               | `false`  | `number`                                                | `0`      | Initial viewport pitch.                                                                                                                                                            |
| `bearing`             | `false`  | `number`                                                | `0`      | Initial viewport bearing.                                                                                                                                                          |
| `cooperativeGestures` | `false`  | `boolean`                                               | `true`   | If `true`, scroll zoom will require pressing the `ctrl` or `⌘` key while scrolling to zoom map, and touch pan will require using two fingers while panning to move the map.        |
| `marker`              | `false`  | `{ lat: number; lng: number; icon?: "pin" \| "house" }` |          | If provided, will render Local Content using a pin marker. The marker can be used to symbolize a location being analyzed. This value is typically the same as the `lat` and `lng`. |
| `distanceUnit`        | `false`  | `"metric" \| "imperial"`                                | `metric` | Primarily used for the commute calculator. Will display the distance in mi/yd under the imperial system or km/m under the metric system.                                           |
| `mapProvider`                | `false`  | `{ name: "maptiler" \| "google"; key?: string }`                                                | `{ name: "maptiler" }`    | Desired map provider data; `key` is only required if `name` is set to `"google"`.

##### "demographics" specific options

| Name    | Required | Type                | Default                | Description                                                                                                                                                                                                                                  |
| ------- | -------- | ------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | `false`  | `boolean \| string` | `"Local Demographics"` | Setting the title to a string will replace the localized internal title. Setting the title to false will hide the title altogether. If you choose to set your own string, ensure you are sending the correct string when the locale changes. |

### `localLogicSDK.on`

The `on` method takes a callback which is triggered when `create` options when an `event` occurs.

#### Options

`localLogicSDK.on(event, callback)`

| Name       | Required | Type                                | Default | Description                                                     |
| ---------- | -------- | ----------------------------------- | ------- | --------------------------------------------------------------- |
| `event`    | `true`   | `"change"`                          |         | The name of the `event`.                                        |
| `callback` | `true`   | `({ type: string, data: unknown })` |         | The callback to be triggered when the specified `event` occurs. |

### `localLogicSDK.destroy`

The `destroy` method is used to teardown the created SDK.

### `localLogicSDK.update`

The `update` method is used to update the widget with new values. This can be useful when, for example, you want to change the widget location.

#### Options

`localLogicSDK.update(options)`

| Name                          | Required | Type                                                   | Default  | Description                                                                                                                                                                        |
| ----------------------------- | -------- | ------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options.lat`                 | `true`   | `number`                                               |          | Initial viewport latitude.                                                                                                                                                         |
| `options.lng`                 | `true`   | `number`                                               |          | Initial viewport longitude.                                                                                                                                                        |
| `options.zoom`                | `false`  | `number`                                               | `16`     | Initial viewport zoom.                                                                                                                                                             |
| `options.pitch`               | `false`  | `number`                                               |          | Initial viewport pitch.                                                                                                                                                            |
| `options.bearing`             | `false`  | `number`                                               |          | Initial viewport bearing.                                                                                                                                                          |
| `options.cooperativeGestures` | `false`  | `boolean`                                              | `true`   | If `true`, scroll zoom will require pressing the `ctrl` or `⌘` key while scrolling to zoom map, and touch pan will require using two fingers while panning to move the map.        |
| `options.marker`              | `false`  | `{ lat: number; lng: number; icon?: "pin" \| "house"}` |          | If provided, will render Local Content using a pin marker. The marker can be used to symbolize a location being analyzed. This value is typically the same as the `lat` and `lng`. |
| `distanceUnit`                | `false`  | `"metric" \| "imperial"`                               | `metric` | Primarily used for the commute calculator. Will display the distance in mi/yd under the imperial system or km/m under the metric system.                                           |

## TypeScript Support

Local Logic SDKs JS comes packaged with TypeScript declarations.