Kamome

Kamome is a library for iOS and Android apps using the WebView. This library bridges a gap between JavaScript in the WebView and the native code written in Swift, Java or Kotlin.

Kamome provides common JavaScript interface for iOS and Android.

If you build Flutter apps with the WebView, see kamome_flutter for the Flutter plugin.

Quick Usage

Sends a message from the JS code to the native code

1. Sends a message from the JavaScript code

   // JavaScript
   
   import { KM } from "kamome"
   
   // Uses async/await.
   try {
       // Sends `echo` command.
       const result = await KM.send('echo', { message: 'Hello' });
       // Receives a result from the native code if succeeded.
       console.log(result.message);
   } catch(error) {
       // Receives an error from the native code if failed.
       console.log(error);
   }

2. Receives a message on iOS

   // Swift
   
   private lazy var webView: WKWebView = {
       let webView = WKWebView(frame: self.view.frame)
       return webView
   }()
   
   private var client: Client!
   
   override func viewDidLoad() {
       super.viewDidLoad()
   
       // Creates the Client object with the webView.
       client = Client(webView)
   
       // Registers `echo` command.
       client.add(Command("echo") { commandName, data, completion in
           // Received `echo` command.
           // Then sends resolved result to the JavaScript callback function.
           completion.resolve(["message": data!["message"]!])
           // Or, sends rejected result if failed.
           //completion.reject("Echo Error!")
       })
   
       let htmlURL = Bundle.main.url(forResource: "index", withExtension: "html", subdirectory: "www")!
       webView.loadFileURL(htmlURL, allowingReadAccessTo: htmlURL)
       view.addSubview(webView)
   }

   [NOTE] This framework supports WKWebView only. UIWebView is not supported.

3. Receives a message on Android

   // Kotlin
   
   private var client: Client? = null
   
   override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      setContentView(R.layout.activity_main)
   
      val webView = findViewById<WebView>(R.id.webView)
   
      // Creates the Client object with the webView.
      client = Client(webView)
   
      // Registers `echo` command.
      client.add(Command("echo") { commandName, data, completion ->
          // Received `echo` command.
          // Then sends resolved result to the JavaScript callback function.
          val map = HashMap<String?, Any?>()
          map["message"] = data!!.optString("message")
          completion.resolve(map)
          // Or, sends rejected result if failed.
          //completion.reject("Echo Error!")
      })
   
      webView.loadUrl("file:///android_asset/www/index.html")
   }

Sends a message from the native code to the JS code

1. Sends a message from the native code on iOS

   // Swift
   
   // Send a data to the JS code.
   client.send(["greeting": "Hello! by Swift"], commandName: "greeting") { (commandName, result, error) in
       // Received a result from the JS code.
       guard let result = result else { return }
       print("result: \(result)")
   }

2. Sends a message from the native code on Android

   // Kotlin
   
   // Sends a data to the JS code.
   val data = HashMap<String?, Any?>()
   data["greeting"] = "Hello! by Kotlin"
   client?.send(data, "greeting") { commandName, result, error ->
      // Received a result from the JS code.
      Log.d(TAG, "result: $result")
   }

3. Receives a message on the JavaScript code

   // JavaScript
   
   // Adds a receiver that receives a message sent by the native client.
   KM.addReceiver('greeting', (data, resolve, reject) => {
       // The data is the object sent by the native client.
       console.log(data.greeting);
   
       // Runs asynchronous something to do...
       setTimeout(() => {
   
           // Returns a result as any object or null to the native client.
           resolve('OK!');
           // If the task is failed, call `reject()` function.
           //reject('Error message');
       }, 1000);
   });

Include Library in Your Project

1. JavaScript

npm

1. npm install

   npm install kamome
   

2. Write following import statement in JavaScript

   import { KM } from "kamome"

Manual Installation

1. Download latest Kamome SDK

2. Import kamome.umd.js

   <script src="/path/to/kamome.umd.js"></script>
   <script>
     const KM = window.Kamome.KM;
   </script>

2. iOS App

Swift Package Manager

Kamome is available through Swift Package Manager. To install it using Xcode, specify the git URL for Kamome.

https://github.com/HituziANDO/kamome.git

CocoaPods

Kamome is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "kamome"

Carthage

Kamome is available through Carthage. To install it, simply add the following line to your Cartfile:

github "HituziANDO/kamome"

You run the following command in the Terminal.

carthage update --use-xcframeworks

Manual Installation

1. Download latest Kamome SDK
2. Drag & drop kamome.xcframework into your Xcode project
3. Click General tab in your target
4. In Frameworks, Libraries, and Embedded Content, Select "Embed & Sign" for kamome.xcframework

Import Framework

Write the import statement in your source code

import kamome

3. Android App

Gradle

Add the following code in build.gradle(project level).

allprojects {
    repositories {
        maven {
            url 'https://hituziando.github.io/kamome/android/repo'
        }
    }
}

Add the following code in build.gradle(app level).

dependencies {		
    implementation 'jp.hituzi:kamome:5.3.4'
}

Manual Installation

1. Download latest Kamome SDK
2. Copy kamome.aar to YOUR_ANDROID_STUDIO_PROJECT/app/libs directory
3. Sync Project in AndroidStudio

Configuration

Timeout to request from the JS code to the native code

KM.send method in JavaScript expects a resolve or reject response will be returned in a duration. If the request is timed out, it's the callback calls reject with the requestTimeout error. You can change default request timeout. See following.

// JavaScript

// Set default timeout in millisecond.
KM.setDefaultRequestTimeout(15000);

If given time is less than or equal to 0, the request timeout function is disabled.

If you want to specify a request timeout individually, you set a timeout in millisecond at KM.send method's 3rd argument.

// JavaScript

// Set a timeout in millisecond at 3rd argument.
const promise = KM.send(commandName, data, 5000);

Optional: console.log for WKWebView on iOS/macOS

The ConsoleLogAdapter class enables to output logs by console.log, console.warn, console.error, and console.assert in JavaScript to Xcode console.

// Swift

ConsoleLogAdapter().setTo(webView)

Use Custom Logger

The ConsoleLogAdapter uses print method to output a log by default. If you use your custom logger, you implement ConsoleLoggable protocol. See following code.

// Swift

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        let consoleLogAdapter = ConsoleLogAdapter()
        // Set the custom logger.
        consoleLogAdapter.logger = self
        consoleLogAdapter.setTo(webView)
    }
}

// Implement ConsoleLoggable protocol.
extension ViewController: ConsoleLoggable {
    public func consoleLog(_ logMessage: Any) {
        // TODO: Output a `logMessage` with the custom logger.
    }
}

Browser Alone

When there is no Kamome's iOS/Android native client, that is, when you run with a browser alone, you can register the processing of each command.

// JavaScript

KM.browser
    .addCommand("echo", function (data, resolve, reject) {
        // Received `echo` command.
        // Then sends resolved result to the JavaScript callback function.
        resolve({ message: data["message"] });
        // Or, sends rejected result if failed.
        //reject("Echo Error!");
    });

Sample App

More info, see my iOS sample project and Android sample project.