# Vendor Javascript

## Directory Location

```
sample-integration/
├── vendor/
|    └── google.js
```

## Summary

Vendor files are javascript files that are loaded alongside your integration. They can be used to inject third-party javascript libraries such as the google maps API.

You can specify vendor files by including them in the [`javascript` property of the configuration](/integrations/build-an-integration/configuration-file.md#javascript).

When an integration is first started or reloaded, any javascript files specified by the `javascript` property in your config will be executed. This gives you an opportunity to load third party scripts.

## onSettingsChange(callback)

**optional |** *function*

| Parameter | Description                                                               |
| --------- | ------------------------------------------------------------------------- |
| callback  | Function to be called when the user updates settings for the integration. |

You can register a callback to the `onSettingsChange` event by passing a callback to the `onSettingsChange` method. This callback will be invoked anytime the user updates settings for the integration. The callback function being invoked will be passed three parameters.

### callback(integration, userConfig, userOptions)

**required |** *function*

| Parameter   | Description                                                                               |
| ----------- | ----------------------------------------------------------------------------------------- |
| integration | the integration object passed into the `init` function                                    |
| userConfig  | a user configuration object which contains settings information for the integration       |
| userOptions | a user options object which contains the user's current option values for the integration |

#### integration

The `integration` variable contains all information about the integration including `userOptions` and `userConfig`.

```javascript
// Sample integrations object
{
    "type": "wikipedia",
    "name": "",
    "onChangeCallbacks": [],
    "config": {
        "name": "Wikipedia",
        "acronym": "Wiki",
        "title": "Wikipedia",
        "block": {
            "component": {
                "file": "./components/block.js",
                "content": ""
            },
            "template": {
                "file": "./template/block.hbs",
                "content": "",
                "compiled": ""
            }
        },
        "main": "./integration.js",
        "description": "Lookup pages in Wikipedia to find contextual information in summaries.",
        "version": "0.0.2",
        "private": true,
        "dependencies": {
            "request": "^2.75",
            "lodash": "^4.16",
            "async": "^2.0",
            "unirest": "^0.5.0"
        },
        "javascript": []
    },
    "userConfig": {},
    "userOptions": {},
    "uniqueId": 1486176346806,
    "summaryComponentName": "integrations/default-summary",
    "blockComponentName": "integrations/wikipedia-1486176346806-block"
}
```

#### userConfig

The `userConfig` object contains information about the integration such as whether or not the user is subscribed, the color chosen by the user, and cache options for this integration.

{% code title="" %}

```javascript
// Sample userConfig object
{
  "name":"Wikipedia",
  "acronym":"Wiki",
  "color":"rgb(200,200,200)",
  "status":"running",
  "starts":1,
  "subscribed":false,
  "path":"/app/polarity-server/integrations/wikipedia",
  "description":"Lookup pages in Wikipedia to find contextual information in summaries.",
  "cacheTtl":300,
  "cacheIsEnabled":true,
  "cacheIsPerUser":true,
  "cacheExpirationCron":null,
  "cacheCompressionEnabled":true,
  "cacheLookupMisses":true,
  "cacheStatus":"OK",
  "messagesReceived":3,
  "messagesSent":0,
  "integrationMetrics":"wikipedia"
}
```

{% endcode %}

#### userOptions

Contains the option values for the current user. For example, if you have an integration option called `apiKey` you could pass this `apiKey` to another API.  

```javascript
// Sample userOptions Object
{
  "apiKey": "klsjadio1j23oij3412oij4",
  "username": "ed",
  "lookupHashes": true
}
```

{% hint style="warning" %}
Options that are set to `admin-only` will not show up in the `userOptions` object as the user does not have access to these values on the client.
{% endhint %}

### Example

The following code provides an example of how you would setup your `vendor.js` file to take advantage of the `onSettingsChange` callback.

{% code title="vendor.js" %}

```javascript
'use strict';

function init(integration, userConfig, userOptions){
    // load some files here
}

// This will be called when integration settings are changed
// including the first time the integration is loaded
onSettingsChange(init);
```

{% endcode %}

If you want to run some javascript and ensure it runs only once, you can add a flag to indicate that the code has already run and then check the flag before running your code.

{% code title="vendor.js" %}

```javascript
'use strict';

let hasRun = false;

function init(integration, userConfig, userOptions){
    hasRun = true;
    if(hasRun === false){
       // do something here and it will only run one time    
    }
}

// This will be called when integration settings are changed
// including the first time the integration is loaded
onSettingsChange(init);
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.polarity.io/integrations/build-an-integration/vendor.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.