Going Native with Wisej.NET Hybrid

by Jon Hilton

If you're targeting native devices like Android or iOS, then Wisej.NET's Hybrid apps can help you build your app quickly (using the Wisej.NET ecosystem) and tap into device specific functionality when you need it.

Hybrid apps are native apps which run on your target device's hardware (for example, that old Android phone have lying around!)

With Wisej.NET's Hybrid projects you can use WiseJ.NET to build your application largely as you would if you were targeting desktop or the web.

Plus you can interact with Device APIs, such as biometrics, the status bar, flashlight etc.

But how does it work?

Let's explore the high level architecture of hybrid apps, and the Wisej.NET projects you'll need to get up and running.

Hybrid Client Application

The first thing you'll need is the application that will actually run on the native device.

This is the one that will be compiled to a platform specific executable for your target device(s).

To create this, look for the project template called Wisej.NET Hybrid Client Application.

When you create a hybrid client application project you'll be asked which platforms you want to target, and how you want to run your Hybrid app (App Mode).

Specifically you'll be asked whether you want to run your Hybrid app remotely or locally.

Which begs the question, what exactly is Local or Remote when we're talking about Hybrid apps?

To answer that, we need to understand how the Hybrid client app actually works.

How the Hybrid Client App works

The client app has two primary jobs:

• Display your app (via a WebView component)

• Enable interactions with the native device (via a JavaScript bridge)

Whether you opt for a local or remote Wisej.NET app the hybrid client itself will always run on the device.

It will be compiled to executables that will run on the device(s) you're targeting.

There it uses a WebView to render your Wisej.NET application and handle interactions (such as when the user selects items on the screen, or enters text).

The client project is of limited use by itself. It needs another project which it can render via the WebView component.

This is where you get to choose whether you want that separate project to be Local or Remote.

But what's the difference between the two options?

Local Project

A local project, also known as an Offline project, will be deployed alongside your native client app.

It will run on the native device itself (via an embedded web server).

This offers more options for interacting with the native device APIs (more on that shortly) but also means you have to redeploy your native app every time you make changes.

Choosing Local/Offline requires you to push new versions out via the relevant app store(s) for your target platform(s) whenever you wish to deploy a new version.

Remote Project

A remote project is a Wisej.NET project which can run anywhere on the Internet (wherever you choose to deploy it).

You can use any Wisej.NET web application for this, or the dedicated Wisej.NET Hybrid Remote Application template.

In the config for the Hybrid Client App you can specify the URL for the remote site:

builder
    .UseMauiApp<App>()
    .RegisterAppServices()   

    .UseWisejHybrid((config) =>
    { 
        // Provide the startup URL for the Hybrid WebView.
        config.StartupUrl = "http://localhost:5000";
    });

The Hybrid Client App will then render the remote site via a WebView control.

The big benefit here is you can easily deploy updates to the web server and all devices which are pointing to that hosted web page will automatically use the latest version.

This saves paying the "deployment tax" of getting the app through the release cycle for the various app platforms, and makes it faster/easier to deploy your app.

It does however mean your app is dependent on having a live connection to the Internet. If you need offline capability Local/Offline apps are a better bet.

Interact with Device APIs

With either of the hosting options your users can view and interact with the app (whether it's running locally, or hosted via a web server).

But this alone would be pretty limiting if you couldn't also write code in your application to interact with the device.

For example, you might want to change the colour or text in the status bar, or read data from the device's sensors.

For that, your app, running via the WebView, needs a mechanism to reach 'outside' of the WebView, to make calls to the device.

This is where the JavaScript bridge comes in.

You can make calls to the Device singleton in your Wisej.NET application, to interact with the various device APIs.

Those interactions are handled via the JavaScript Bridge (part of the WebView, running on the device) which makes the underlying calls to the relevant device API.

Device.Flashlight.TurnOn(); 

Here, for example, we're able to switch on the device's flashlight.

We don't need to know the specifics of how to make this work via Android, or iOS, as that's handled by the Device abstraction.

When we make the call to Device.Flashlight the instruction to switch it on will be sent to the device, from the WebView via the JavaScript bridge.

Interacting with the device via MAUI

So far everything we've explored works for both local/offline and remote projects.

But if you opt for a local/offline project you can interact with the device via .NET MAUI as well.

First you need to enable MAUI in the .csproj file for your Local app.

<PropertyGroup>
    <UseMaui>true</UseMaui>
</PropertyGroup>

With that in place you can now make calls to Microsoft.Maui.

#if ANDROID || IOS
    Microsoft.Maui.Devices.Vibration.Default.Vibrate(TimeSpan.FromSeconds(1));
#endif

Here we make the device vibrate for one second using .NET MAUI's API.

Incidentally, this also shows how to target specific platforms in your code. In this case this code will only execute for Android or iOS devices.

In Summary

Wisej.NET hybrid opens the door to building native apps.

When you create a hybrid app you need to choose whether to deploy your app to the native device, or host it externally.

From there you can write code to interact with the device via the Device singleton and/or, in the case of Local applications, Microsoft MAUI.

To continue your hybrid journey check out the step by step guide below:

pageBuilding a Simple app with Wisej.NET Hybrid