swizi v6.0.0

Swizi Plugin JS

A Swizi app provides a way to access to native method such as retrieve the user, call generic actions or even getting a bar code inside your web plugin. To perform a native call, you need to import swizi.js or swizi.min.js in your index.html. You must have swizi.js next to your index.html to be sure everything is called at the right moment.

New in the 4.2.1 SDK

Close App (Android)

Go to previous release notes

Summary

• Swizi Plugin JS
• New in the 4.2.1 SDK
• Summary
• Init
• Export your plugin to use it in a Swizi app
• Responses
• Logs - Check if plugin bridge is ready
• Native calls - Login user - Logout user - Get connected user - Refresh user datas - Get current token - Get AuthWS token - Get user profile photo - Get user location - Get an app color - Get media - Get current lang - Get space ID - Change space ID - Navigation - Push new page - Close page - Open menu - Set navigation bar button - Remove navigation bar button - Set plugin controls back press - Set navigation bar child mode - Go to welcome screen - Go to notification center - Show spinner - Camera - Take a photo - Read a bar code - GPS Tracking - Start tracking - Stop tracking - Check if tracking is enabled - Close App - Wifi features - Get Wifi infos - Connect to Wifi
• UI - Use Fullscreen (iOS only) - Check if Fullscreen enabled - Set Title - Change status bar appearance - Change status bar color - Get the navigation bar height - Get the status bar height
• Platform - Get platform version
• Generic Actions - List generic actions available for the plugin - Perform a generic action
• Data storage - Get items - Get item - Set item - Delete item - Get files - Get file - Save file - Get Form
• Manifest - Plugin manifest - Plugin icon
• Plugin preview
• Experimental features - iOS - dataConnector
• Custom events
• Colors Identifiers
• Previous release notes - New in the 4.00 SDK - New in the 2.10 SDK - New in the 2.9 SDK - New in the 2.8 SDK - New in the 2.7 SDK - New in the v2.6.0 SDK - New in the v2.4.1 iOS / v 2.4 Android Swizi Player release - New in the v2.4 iOS / v 2.4 Android Swizi Player release - New in the v2.3.1 iOS / v 2.3.1 Android Swizi Player release - New in the v2.3 iOS / v 2.3 Android Swizi Player release
• Breaking Change - New in the v2.2 iOS / v2.2 Android Swizi Player release - New in the v2.1.2 iOS / v2.1 Android Swizi Player release - New in the v2.0.8 iOS / v2.0.6 Android Swizi Player release - Breaking Changes

Init

Once the swizi.js script is imported, there's nothing more to do to init the plugin.

You can listen for the event swiziReady. In the event object, in the detail property, you'll find an object called options.

It contains:

{
	'showMenuButton': true/false,
	'params': {},
}

Export your plugin to use it in a Swizi app

Your plugin is ready. You want to use it inside the app (available in the Player too). Don't panic, everything will be fine.

• 1- Go inside the folder where the files are. You must see the index.html and swizi.js (or swizi.min.js) files here.
• 2- Select all files and folder.
• 3- Then create a zip file with the selection.
• 4- Go to your app in the Swizi Studio
• 5- Select your plugin (or create it) and upload the zip file created via the big button inside the section.
• 6- Watch it inside the Player.

Responses

The methods which doesn't return any values don't provide any response. Other methods (where a result is returned) return a promise. To get the values you need to do like this:

swizi.getUser().then(function(user) { / ...your code... / })

Logs

You can use this method to log text in the specified window on the phone.

swizi.log(type, message)

Type can be any value of the console object in the browser.

Check if plugin bridge is ready

swizi.isPluginBridgeReady()

Return:

true or false

Native calls

This is the differents method you can call and the informations retrieved.

Login user

swizi.loginUser(type, login, password, activationCode)

Return: JSON Object

	{
		"success": true | false,
		"error": "Error string" 
	}

Logout user

swizi.logoutUser()

Return: JSON Object

	{
		"success": true | false,
		"error": "Error string" 
	}

Get connected user

swizi.getUser()

Return: JSON Object

{
  "addressLine1" : null,
  "zipCode" : null,
  "company" : null,
  "country" : null,
  "userID" : "user@user.com",
  "userkey" : null,
  "city" : null,
  "mobilePhone" : null,
  "civility" : 0,
  "fromNetwork" : 0,
  "gender" : 0,
  "phone" : null,
  "login" : "user@user.com",
  "firstName" : "User",
  "role" : null,
  "age" : 0,
  "addressLine2" : null,
  "lastName" : "User",
  "test" : null
}

Refresh user datas

Some actions you may have done can change some user datas (application content, user's infos...). If you wish to force the plugin refresh these datas, you can call this method.

swizi.refreshUserDatas()

Return: no result

Get current token

swizi.getToken()

Return: String

Get AuthWS token

swizi.getAuthWSToken()

Return: String

Get user profile photo

swizi.getUserPhoto(userID)

Return: see custom events

Get user location

swizi.getUserLocation()

Return: see custom events

Get an app color

swizi.getColor("COLOR_IDENTIFIER");

See colors identifiers at the end.

Return: JSON Object

{
  'r': [0 -> 255],
  'g': [0 -> 255],
  'b': [0 -> 255],
  'a': [0 -> 1]
}

Get media

When using a manifest inside the plugin, you can add medias to your plugin dynamically. These medias are the one you upload into the library of the Swizi Studio. With this type of configuration field provided, you don't need to include the medias inside the zip file. Bonus point, it will use the same cache system than other medias of your application.

swizi.getMedia("mediaId")

Return: JSON Object

{
  'success' : [0->1],
		'error': null or string,
		'media': base64String,
		'mimeType': mimeTypeString, 
}

Get current lang

swizi.getLang()

Return: JSON Object

{
	'lang': 'currentLang (fr / en)'
}

Get space ID

swizi.getSpaceId()

Return: JSON Object if there is a space ID

{
	'spaceId': 'THE_CURRENT_SPACE_ID'
}

Change space ID

swizi.changeSpaceId(id)

Return: no error if success, otherwise:

{
	'error': 'reason',
}

Navigation

If your plugin use multiple webpage (without a router inside), you can navigate to these pages using native interactions

Push new page

swizi.navigateTo("index", null, true);

Transition type

• Default: default OS transition
• Modal
• Others will be added in the future

Return: no result

Close page

swizi.back()

Return: no result NB: if called on the root page and with a side menu navigation, it will open the side menu.

Open menu

swizi.openMenu()

Return: no result

Set navigation bar button

You can add a button in the right of the navigation bar (next to the console button when using Le Player). This button when touched sends a swiziEvent (see custom events)

swizi.setNavbarButton("idButton", "absolutePathToIcon")

Return: no result

Remove navigation bar button

swizi.removeNavbarButton("idButton")

Return: no result

Set plugin controls back press

You can take control of the left button of the navigation bar: you can choose if the app stays default, or you can manage yourself the navigation. When calling this method, a "new" button is used instead the default one. When touched, it sends a swiziEvent (see custom events)

swizi.setPluginControlsBackPress(takesControl)

Return: no result

Set navigation bar child mode

After taking control of the left button of the navigation bar, you can change its appearance: the burger icon or the back icon. If isChild is set to true, the back icon will be shown. If set to false, the burger icon will be shown.

swizi.setNavbarChildMode(isChild)

Return: no result

Go to welcome screen

Sometimes, you may need to go back to the welcome screen (or home) or simple push the welcome screen. You can do that by calling:

swizi.goToWelcome(popToRoot)

Return: no result

Go to notification center

To open the notification center available inside a Swizi application (the application must have the notification center activated into the Notifications menu on the Swizi Studio), you can do that by calling:

swizi.goToNotificationCenter()

Return: no result

Open App

You may want to open another app from a plugin. With this method, you can open an app by providing its url-scheme.

swizi.openUrl(urlScheme, inApp)

Return: JSON object containing a property error which can be null if opening the url is a success.

Show spinner

swizi.showSpinner(SHOW_OR_HIDE, MESSAGE);

Return: no result

Camera

Take a photo

swizi.takePicture();

Return: see custom events

Read a bar code

swizi.readQRCode();

Return: see custom events

GPS Tracking

You propably use a geolocalizable user group in your app. If so, from a plugin, you can start/stop GPS tracking.

Start tracking

swizi.activateGPSTracking()

Return: no result NB: a local notification is displayed when the GPS tracking is started

Stop tracking

swizi.deactivateGPSTracking()

Return: no result NB: the local notification which display GPS tracking is removed

Check if tracking is enabled

swizi.isGPSTrackingEnabled()

Return: JSON Object

{
  'enabled': true / false 
}

Close App

swizi.closeApp()

Return: None NB: Quit and close App. Android only feature.

Wifi features

Get wifi infos

swizi.getWifiInfo()

Return: JSON Object

    {
        "data": [String],
        "error": String
    }

Connect to Wifi

swizi.connectToWifi(ssid, pwd, wifiSecurity, identity, eapType, authType, captivePortal)

(available on iOS and Android 10+)

Wifi security values possibility:

Eap type values possibility:

Auth type values possibility:

Return: JSON Object

Return: JSON Object

    {
        "data": [String],
        "error": String
    }

UI

To change native components around the web

Use Fullscreen (iOS only)

You may want to use a fullscreen view for your plugin.

swizi.setFullscreen(withAnimation)

Return: no result NB: To stop fullscreen view, you can recall this method.

Check if Fullscreen enabled

swizi.isFullscreen

Set Title

To change the title you see in the navigation bar.

swizi.setTitle('title');

Return: no result

Change status bar appearance

swizi.setStatusBarLight(true);

Return: no result

Change status bar color

On iOS, it will work only if you set your plugin to use fullscreen. Otherwise, the navigation bar is shown and the status bar is included in it.

swizi.setStatusColor("#000000");

Return: no result

Get the navigation bar height

swizi.getNavBarSize();

Return: int

Get the status bar height

swizi.getStatusBarSize();

Return: int

Platform

###Get platform

swizi.getPlatform();

Return:

ios or android

Get platform version

swizi.getPlatformVersion()

Return: JSON object

for iOS:
{
  "major": 10,
  "minor": 2,
  "patchVersion": 2
}

for Android
{
  "release": "3.4b5",
  "security_patch": "1",
  "sdk_int": "1",
}

Generic Actions

List and perform generic action you added to your plugin

List generic actions available for the plugin

swizi.getGenericActions();

Return: JSON array

[
	{
		'title': 'GENERIC_ACTION_TITLE',
	}
]

Perform a generic action

swizi.performGenericAction('title', 'params');

Return: no result

Data storage

You can store in a private database key/value based informations. You can also get your API Key Values. For methods that accept a label parameter, if one is given, it will use the datasource API Key/Values. If none is given, private database key/value based will be used.

Warning: if a user was logged in, databases are cleaned when logout.

Get items

swizi.getItems(label);

Return: JSON array

if label provided

[
	{
		'label': '...',
		'list': 
				[
					{
						'key': '...',
						'value': '...',
						'scope': '...',
						'param': '...',
					}
				]
	}
]

if no label provided

[
	{
		'label': '...',
		'list': 
				[
					{
						'key': '...',
						'value': '...',
						'scope': '...',
						'param': '...',
					}
				]
	}
	...
]

Get item

swizi.getItemForKey(key, label);

Return: saved string

Set item

swizi.setItemForKey(item, key, label);

Return: no result

Delete item

swizi.removeItemForKey(key);

Return: no result

Get files

You can connect a File datasource to a plugin section. With this method, you can get the local URLs of these files inside the application

swizi.getFiles();

Return: JSON Array

[
	{
		'folder': 'NAME_OF_THE_DATASOURCE',
		'files': [
			{
				'file': 'LOCAL_URL_OF_THE_FILE',
			},
			...
		]
	},
	...
]

Get file

If you have a local URL of a file, you can get the Base64 string of this file.

swizi.getFile('LOCAL_URL_OF_THE_FILE')

or

swizi.getFileNamed('THE_NAME_OF_THE_FILE_WITH_ITS_EXTENSION')

Return: JSON Object

{
	'file': 'base64String',
	'mimeType': 'file's mimeType',
	'error': null,
}

Save file

You can save a file in the directory of the plugin.

swizi.saveFileNamed('BASE_64_REPRESENTATION_OF_THE_FILE', 'FILENAME_WITH_EXTENTION')

Return: JSON Object

{
	'error': null,
}

Get Form

If you have a Form datasource connected to your plugin section, you can access it:

swizi.getForm()

Return: JSON Object

{
	'apiKey': 'YOU_API_KEY',
	'name': 'THE_NAME_OF_THE_FORMS',
	'urlMS': 'THE_URL_OF_THE_FORMS',
}

Manifest

Since version 3.x of the SDK, and by using the corresponding Swizi players (September 2019) it is possible to use manifests in plugins.

The manifest allows you to define parameters to configure a plugin from the studio. Plugins can therefore be reused more easily and configured directly from the studio without the need for the plugin developer.

Example:

• John creates a weather information plugin. He creates in the plugin a manifest that contains a "city" parameter.
• Marc creates a mobile application in which he adds a weather section, it is a "plugin section". He loads the john's plugin. In the studio, he configures the "city" parameter with Paris.

• Marie, creates another mobile application, she also adds a weather section. It sets the "City" parameter to London.

Marie and Marc both used the plugin made by John, without knowing how it is made, and configuring it according to their needs.

Plugin manifest

The manifest is a file named manifest.json that must be placed at the root of the plugin package. It is possible to download an example file from the studio, in a plugin section.

In the plugin, to retrieve the settings made in the studio, just call the getManifest() method.

The manifest.json file accepts the following information:

Plugin icon

It is possible to define an icon that represents the plugin. This icon will be used in the studio in the configuration page of the section that uses the plugin. To define the icon, you must drop a logo.png file at the root of the plugin package.

Plugin preview

It is possible to create a preview version of the plugin. A preview is a javascript/html content that will be displayed inside the tiles of the presentation sections. This feature allows you to display dynamic and personalized content in the presentation sections. The preview of a weather plugin can, for example, be just the temperature and an image representing the weather. For performance reasons, it is recommended to make content simple, refined with little javascript processing. To make a preview available, drop a preview.html file at the root of the plugin package.

Experimental features

For more informations, please contact us.

iOS - dataConnector

swizi.experimental.ios.dataConnector(dataConnector, datas, withCompletion)

Return: JSON Object if JSON valid, if it has a return value and if withCompletion is set to true

Custom events

Some datas comes from native code. To get result from asynchronous call, you need to give a callback to the next method:

swizi.onEvent(function(event){});

You can also remove the event listener by calling:

swizi.removeEvent(function(event){});

To determine which kind of data you'll get, all informations are in event.detail:

{
  'type': 'TYPE_OF_EVENT',
  'value':'VALUE',
  'param': 'PARAM_VALUE',
  'error': 'ERROR_MESSAGE'
}

Colors Identifiers