@ahamove/js-function

The @ahamove/js-function library facilitates seamless communication between web and mobile applications through event-based interactions. Designed specifically for use within the Ahamove app, this Node.js library enables the web application to connect with mobile functionality by defining and handling events on both platforms. This integration supports dynamic interactions, allowing web components to trigger mobile-side actions and respond to mobile events, enhancing the in-app experience by bridging mobile and web capabilities.

Installation

You can install @ahamove/js-function using npm or dynamically load it from a URL.

1. NPM Installation

To install via npm, run:

npm install @ahamove/js-function

2. Dynamic Loading with loadJS

Alternatively, you can use loadJS from @ahm/common-helpers to dynamically load the library as an IIFE bundle:

import { loadJS } from "@ahm/common-helpers";

loadJS(
  "https://vncdn.ahamove.com/public/js-function/{{VERSION}}/index.js"
)
  .then(() => {
    console.log("JSFunction library loaded successfully");
    // Access the library with window.JSFunction
    window.JSFunction.call({
      name: "openPage",
      body: "add_ahamove_deep_link_here",
    });
  })
  .catch((error) => {
    console.error("Failed to load JSFunction library:", error);
  });

Usage

The library supports both module-based and global usage:

• If installed via npm, you can import JSFunction and use it directly.
• If loaded dynamically, JSFunction will be available globally as window.JSFunction.

Importing the Library (NPM)

import { JSFunction } from "@ahamove/js-function";

or import the default export:

import JSFunction from "@ahamove/js-function";

Sending Events

Use the call method to push events to the mobile app. Here are a few examples:

// Open a new order page
JSFunction.call({
  name: "openPage",
  body: "add_ahamove_deep_link_here",
});

// Close the WebView
JSFunction.call({
  name: "close",
});

// Navigate back
JSFunction.call({
  name: "back",
});

Handling Callback with call

You can handle responses from the mobile app directly using the callback parameter in the call function:

JSFunction.call({ name: "getToken" }, (messageEvent) => {
  console.log("Token received:", messageEvent.data);
});

Using window.JSFunction in TypeScript

When loading @ahamove/js-function dynamically via CDN, JSFunction will be available globally as window.JSFunction. To avoid TypeScript errors like Property 'JSFunction' does not exist on type 'Window', you need to declare window.JSFunction in the global scope.

Declare window.JSFunction in TypeScript

Add the following global declaration to your TypeScript file to define window.JSFunction:

import type { JSFunctionType } from "@ahamove/js-function";

declare global {
  interface Window {
    JSFunction: JSFunctionType;
  }
}

This declaration will allow you to access window.JSFunction without TypeScript errors:

window.JSFunction.call({
  name: 'openPage',
  body: 'add_ahamove_deep_link_here',
});

Optional: In case you want to handle the message event yourself

Alternatively, if you prefer managing the response with a message event listener, here’s an example in React:

import React, { useEffect, useState } from "react";
import { JSFunction } from "@ahamove/js-function";

function App() {
  const [callbackData, setCallbackData] = useState(null);

  useEffect(() => {
    const messageHandler = (messageEvent) => {
      console.log("Message received:", messageEvent);
      setCallbackData(JSON.stringify(messageEvent.data));
      if (messageEvent.data?.webinapp) {
        console.log("Event data contains webInApp:", messageEvent.data);
      } else {
        console.warn(
          "Event data does not contain webInApp:",
          messageEvent.data
        );
      }
      window.removeEventListener("message", messageHandler);
    };

    window.addEventListener("message", messageHandler);

    JSFunction.call({ name: "getToken" });

    return () => window.removeEventListener("message", messageHandler);
  }, []);

  return <div>Callback Data: {callbackData}</div>;
}

export default App;

Optional: Enable Logging

For debugging purposes, you can enable logging:

JSFunction.enableLogger(true);

This will log event information to the console.

API Reference

JSFunction.call(data: { name: WebInAppEvent, title?: string, body?: object }, callback?: (event: MessageEvent) => void)

Send a WebView event to the Ahamove mobile application.

• data: An object containing event details.
  • name: The event name, one of the WebInAppEvent types.
  • title: Optional title for events involving UI updates.
  • body: Optional data for event-specific parameters.
• callback: Optional callback function to handle responses from the mobile app.

JSFunction.enableLogger(enable: boolean)

Enable or disable logging to the console for debugging purposes.

Here's an updated README.md that includes instructions for using @ahamove/js-function in TypeScript, both as an npm module and as a global variable accessed through window.JSFunction. Additionally, it includes steps for declaring window.JSFunction with TypeScript to avoid type errors.