The Pixview plugin SDK lets you develop your own plugin to view new types of content in Pixview. The SDK sets up communication between your plugin and the Pixview player and provides multiple methods and events.

• Node.js 16.14.0 or higher

Run npm install to install required dependencies. To help you develop a plugin, this repo offers a small CLI tool that supports a couple of commands. To create a new plugin, run pixcli new <name>.

To test your plugins, run pixcli test to start a local server. You can then visit localhost:8080 to view the test environment. This will allow you to open your plugin and load it into an iframe just as it would in the Pixview Player. Values can be set for the parameters as defined in your manifest.json and events can be simulated. Your plugin code can also directly be edited from this page. To view your changes, click reload plugin.

The request method lets you safely use secrets in an HTTP request. Instead of using an actual API token as value, you insert a placeholder when making the request. The actual value is inserted later by Pixview.

To configure a secure parameter, set the secure option to true. Then, when calling the request() method, use the parameter key as placeholder like this:

const options = {
	url: "https://api.example.com/",
	type: "GET", 
	headers: {
		Authorization: "Bearer {api-token}"
	},
};
	
client.request(options).then((response) => { 
	console.log(response);
});

When you've sufficiently tested your plugin, run pixcli package <directory> to validate and package your plugin into a zip archive. You may also do this manually. Pixview will accept HTML, JavaScript, and image files. Make sure you validate your plugin using pixcli validate <directory> before uploading. The contents of your zip file should look something like this:

• index.html
• sdk.js
• manifest.json
• another_script.js
• cute_dog.jpg

Each plugin must define a manifest.json file that describes the plugin. A plugin can be configured as follows:

{
	"name": "My plugin",
	"description": "A new empty plugin",
	"version": "0.1",
	"parameters": [
		{
		"name": "Text Parameter",
		"key": "text_param",
		"description": "This parameter accepts a text value",
		"type": "text",
		"optional": false
		}
	]
}

The name of your plugin.

A short description of the functionality of your plugin.

Version number used to update your plugin.

Defines the list of parameters your plugin accepts as input by a user. The following properties are available:

• name Name of parameter shown in the portal.
• key Unique key used to identify parameter.
• description Short description of parameter.
• type Datatype of parameter. Options are:
  • text - JSON string type, shown as text input in portal.
  • number - JSON number type, show as number input in portal.
  • checkbox - JSON boolean type, shown as checkbox in portal.
  • password - JSON string type, shown as password input in portal.
  • multiline - JSON string type, shown as textarea in portal.
• optional Indicates whether or not parameter can be ignored by a user.
• secure If set to true, value will be encrypted. Used for API tokens.

A plugin is essentially an index.html file containing different HTML elements and JavaScript. To allow the plugin to run, index.html will have to import the SDK file. The SDK will facilitate the communication between your plugin and the Pixview Player. After initializing the client, the following methods are available:

Requests list of parameters as defined by manifest.json.

Returns an array of parameters with user inputted values.

const client = PIXClient.init();

client.getParams().then((response) => {
	console.log(response);
	// {"text_param": "Hello World!"}
})

Makes an HTTP request.

• options an object containing one or more of the following properties:
  • url
  • method
  • body
  • headers

Returns response body

const options = { 
	url: "https://api.example.com",
	type: "GET"
};
	
client.request(options).then((response) => {
	console.log(response);
});

Allows you to add handlers to events. Currently only the active event is available, which returns true or false when the plugin is active or inactive respectively.

• name name of the event
• handler attached function

client.on('active', function(e) {
	// do whatever
})

Saves data to localStorage. Keep in mind values stored in localStorage are always strings.

• data string saved in localStorage

client.saveToLocalStorage('Hello World!').then(() => {
    	console.log('Saved in storage');
});

Request saved plugin data in localStorage

client.getFromLocalStorage().then((response) => {
    	console.log(response);
    	// 'Hello World!'
});

Get information about device where plugin is currently being displayed.

client.getPlayer().then((response) => {
    	console.log(response);
    	// {
    	   location: Object {
    	   	id: 1,
    	    	name: "XIP",
    	   	latitude: "52.2216067616560050", … 
    	    },
    	    name: "Test Player",
    	    status: "active",
    	    }
});

Returns a Player object.