Page tree
Skip to end of metadata
Go to start of metadata

This guide explains how to create and use iOS plugins in Smartface.

iOS Plugin – Hello World

Create iOS Plugin Xcode Project

Smartface CLI (Command Line Interface tool) is a prerequisite for plugin development. For more information and installation instructions, visit the CLI page.

The following CLI command is used for creating iOS plugin template Xcode project. It is recommended to create the Xcode project folder first and then Change Directory (CD) into it.

From Mac, open terminal and use the following command:

smfc --task=create_iOSPlugin [--path=…] [--playerPath=…]
  • task :. “create_iOSPlugin” is specified to create iOS plugin template.
  • path : Path of the template project to be created. If not provided, current folder is used.
  • playerPath : Path of the base player or project to create the template from. If not provided, currently associated versions with the CLI are used. There is some post processing applied to the zip file content when extracted, do not try to use zip file as is.

It will be created as below:

Write HelloWorld Plugin

Now open this project with Xcode, right click on Plugins folder then add new file, as follows:

Name this new class as “HelloNotifier”.

For HelloWorld application let's create a function named sayHello as below and HelloNotifier.h will look like:

#import <JavaScriptCore/JavaScriptCore.h>

@interface HelloNotifier : NSObject

- (void)sayHello:(JSValue*)onSuccess;

@end

And HelloNotifier.m will look like:

#import "HelloNotifier.h"

@implementation HelloNotifier

- (void)sayHello:(JSValue*)onSuccess {
    NSString *helloText = @"Hello Smartface Plugin";
    [onSuccess callWithArguments:@[helloText]];
}

@end

To expose your HelloNotifier function to JavaScript, you need to write your functions in a protocol that conforms to JSExport, and then let HelloNotifier conforms to this protocol.

To create instances of HelloNotifier in JavaScript, you need to expose init function, so it is mandatory to put it inside JSExport and implement it.

Finally HelloNotifier.h will look like:

#import <JavaScriptCore/JavaScriptCore.h>

@protocol HelloNotifierExport <JSExport>

- (instancetype)init;
- (void)sayHello:(JSValue*)onSuccess;

@end

@interface HelloNotifier : NSObject<HelloNotifierExport>

- (void)sayHello:(JSValue*)onSuccess;

@end

Finally HelloNotifier.m will look like:

#import "HelloNotifier.h"

@implementation HelloNotifier

- (instancetype)init {
    self = [super init];
    if (self) {
    }
    return self;
}

- (void)sayHello:(JSValue*)onSuccess {
    NSString *helloText = @"Hello Smartface Plugin";
    [onSuccess callWithArguments:@[helloText]];
}

@end

Register HelloWorld Plugin For Smartface

Open SmartfaceAppDelegate, inside willSetCustomPluginsOnContext, write the following:

#import "HelloNotifier.h"
 
- (void)willSetCustomPluginsOnContext:(JSContext*)context {
	//Register your plugin's class
    context[@"HelloNotifier"] = [HelloNotifier class];
}

Generate HelloWorld Plugin For Smartface

Like an npm package, plugins use a “package.json” file to identify it's contents. It is recommended to use following command to create a new “package.json” file after Changing Directory (CD) into Xcode project folder:

npm init

This will use command line interface to create a new “package.json” file or modify the existing one. Based on the approach, you may need to modify the “package.json” file manually.

In the file, add following fields to the JSON:

  • OS {string} – Identifies if it is an iOS or an Android plugin. Possible values are : “Android” or “iOS”. Since we're developing an iOS plugin, this will be iOS.
  • cpu {array.string} – Identifies architecture types supported by the plugin. Possible values are: “x86”, “ARM”, “ARM64”. For Android, it can be “x86” or “ARM” or both. For iOS, it is required to have “ARM” and “ARM64” together.

Remove the following field from the JSON:

  • main

Also, you can copy the following package.json and change it's values. Make sure that "name" value must be in small letters.

{
  "name": "hellonotifier",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "OS": "iOS",
  "cpu": [
    "ARM",
    "ARM64"
  ]
}

After performing the necessary steps as described above, plugin zip file can be created using the following CLI command. Change Directory (CD) to the Xcode project folder and type:

smfc --task=generate_iOSPluginZip

If the operation is completed successfully, a zip file will be created inside the Xcode project folder. This file is ready to use and ready to distribute for Smartface Developer to use. You can rename the .zip file as your plugin name.

Use HelloWorld Plugin In Smartface Cloud Workspace

After generating your plugin zip, open your Smartface Cloud workspace, drag and drop your plugin zip file under plugin folder.

Now open your project.json file

then navigate to build → input → iOS → plugins, then finally inside plugins add the following:

"hellonotifier": {
    "url": "if you will get the plugin data from url please write here",
    "path": "plugins/iOS/hellonotifier.zip",
    "active": true
}

For example:

{
	"build": {
		"input": {
			"ios": {
				"plugins": {
					"hellonotifier": {
						"url": "",
						"path": "plugins/iOS/hellonotifier.zip",
						"active": true
					}
				}
			}
		}
	}
}

Important thing to consider, "hellonotifier" name written in project.json in your workspace must match "hellonotifier" name written in package.json before creating the plugin zip file.

Now let's create a new HelloNotifier object and create a textButton in order to use its onPressed event.

var helloworld = new HelloNotifier();
var myHelloButton = new SMF.UI.TextButton({
		left : "10%",
		top : "15%",
		height : "10%",
		width : "80%",
		text : "say hello",
		onPressed : function () {
			helloworld.sayHello(function (e) {
				alert(e);
			});
		}
	});
page1.add(myHelloButton);

When this button is tapped, it will show an alert on iOS device as below: