KEPLIN Docs

Connecting the phone to an app

Adding an app to KeplinGo with a QR code or by hand, the home screen shortcut, several apps on the same phone, and what the phone adds to the screens.

Right after installing, KeplinGo doesn't know which installation to connect to or which apps to open. You add each app once, with the installation address and the app identifier, and from then on it has its own shortcut on the home screen.

There are two ways to add an app. The QR code is the one to use when you prepare phones for other people; typing by hand is for when there's no QR code.

Add an app with a QR code

The QR code is generated on the platform and carries the installation address and the chosen app.

  1. Open Settings in the sidebar.
  2. Scroll down to the Mobile app panel and find Connect by QR.
  3. Open the Pick the app… selector and choose the app, for example Customer Management.

The app selector of the QR connection, with the installation's apps
The app selector of the QR connection, with the installation's apps

  1. The code appears below, with the link written beside it and the Copy link button.

The QR code generated for the Customer Management app, with the link beside it
The QR code generated for the Customer Management app, with the link beside it

  1. On the phone, with KeplinGo installed, point the camera at the code and open the link it shows.

KeplinGo opens on the Connect to an app screen, already filled in. The QR code saves the typing, but it doesn't add the app by itself: the person still taps Validate address and reads the app name before signing in.

Note

The QR code carries the app's first published address, and the phone opens the published version. In the Address field, the Platform address (working version) option is for testing what hasn't been published yet.

Tip

The QR code is the practical way to prepare a whole team: project it in a meeting, or print it next to the phones. Each person points the camera and only has to sign in with their own credentials.

Add an app by hand

  1. Open KeplinGo. With no app configured, the Connect to an app screen appears. With apps configured, the Your apps list appears: tap Add app.
  2. Enter the Server address: the address where the platform answers, such as https://your-app.example.com. Without https://, KeplinGo adds it.
  3. Enter the App: the application's short identifier, such as gestao-clientes. It's the same one that appears in its addresses.
  4. Tap Validate address.

KeplinGo asks the server whether the app exists, and answers in one of these ways:

Answer What to do
You're connecting to "Customer Management", with the app icon It's right: tap Add and open.
"That server doesn't have that app." The address is right, the app identifier isn't.
"Couldn't connect to that address." The address is wrong, or the phone can't reach the server.
"That address isn't an app on this platform." The address answers, but it isn't a Keplin installation.
"Enter an https:// address." The address won't do: KeplinGo only accepts secure connections.

Note

Validation exists so that the app name is read before anyone gives credentials to anyone. That's why it remains an explicit tap, even when the QR code has already filled everything in.

Sign in to the app

Add and open saves the app and opens it on its sign-in screen: the same sign-in screen that the app shows in the browser, with the design you gave it. The credentials are the application's, not the platform's: the accounts managed in the app settings.

The Customer Management sign-in screen at the width of a phone. This screen got no design of its own for the phone and is served with the web design, so the labels get cramped. The screen builder chapter shows how to give each device its own design.
The Customer Management sign-in screen at the width of a phone. This screen got no design of its own for the phone and is served with the web design, so the labels get cramped. The screen builder chapter shows how to give each device its own design.

The session is kept on the phone and renews itself while you work; only a long period of inactivity ends it.

If the app has authentication providers (see Sign in with authentication providers), each one's button opens the service's page in a Chrome tab. When the person finishes signing in, KeplinGo comes back to the front with the app already open. Active Directory signs in through the fields of the sign-in screen, as in the browser.

The home screen shortcut

The first time it opens an app, KeplinGo asks Android to put a shortcut to it on the home screen. Android shows its own confirmation dialog, with the app name and icon.

  • To add the shortcut, tap Add to home screen in the dialog.

The shortcut opens the app directly, without going through the list. It has the app name and the icon chosen in App settings ▸ General ▸ Phone icon (see Creating and managing apps); without an image, it has the app icon drawn on the theme's primary color. When the name or the icon change on the platform, the shortcut updates itself the next time the app opens.

Note

Android doesn't let an app change the name it was installed with. In the phone's app list, KeplinGo always appears as KeplinGo; each app's name and icon are on the shortcuts. The launcher may add a small badge with the KeplinGo icon to the shortcut.

If you dismiss the dialog, you can ask for the shortcut later: in the Your apps list, tap More options (the three dots) next to the app and choose Add to home screen.

On Android 7, the shortcut keeps the name and icon it had when it was created: Android only allows shortcuts to be updated from Android 8 onwards.

Several apps on the same phone

KeplinGo keeps as many apps as needed, from the same installation or from different ones.

  • Each app opens in its own Android task. In recent apps, each one has its own card, with its icon, and switching from one to the other loses nothing that was open in either.
  • Each app has its own session. Signing in to or out of one doesn't touch the others.
  • The KeplinGo icon in the app list opens the Your apps list. With only one app configured, it opens that app directly.
  • Touching and holding the KeplinGo icon shows the configured apps and Add app.

Inside an app, the user menu has the KeplinGo apps entry, which opens the list. That's how you add another app without leaving the one that is open.

What you see on the phone

KeplinGo shows the screens you designed for the phone, with the phone navigation (side menu or bottom bar, as you configured it) and the screen you marked as the home screen.

The home screen of the Customer Management app, at the width of a phone
The home screen of the Customer Management app, at the width of a phone

It's the same runtime as the browser: everything that works in the browser works here, including custom widgets, modals, reports, and the full SDK. There's no second version of the application to maintain.

What the phone adds:

Piece In KeplinGo
Location keplin.device.location() reads the phone's GPS. Android asks for permission the first time. keplin.device.platform is "android".
Camera The File upload widget with the camera turned on opens the phone's camera. Custom widgets that use the live camera (a code reader, for example) also get it, with Android's permission.
Files Reports, exports, and attachments open in the phone app that reads that type of file, such as the PDF viewer; if there's none, the share sheet opens.
External links An address outside the app opens in the phone's browser; a phone number or an email address opens in the matching app.
Back button Goes back to the app's previous screen. On the first screen, it goes to the home screen and the app stays in recent apps.

When the network fails

Without a network, KeplinGo shows the No connection notice, with the Try again button. Screens come from the server, so there's no local copy to show.

Remove an app

  1. Open the Your apps list: tap the KeplinGo icon, or choose KeplinGo apps in an app's user menu.
  2. Tap More options (the three dots) next to the app and choose Remove.
  3. Confirm with Remove.

The app leaves KeplinGo and its session ends. Android doesn't let KeplinGo delete the home screen shortcut: the shortcut turns grey, with a notice that the app was removed, until you remove it by hand.

Why doesn't it work…?

  • …the QR code? Check that the phone has KeplinGo installed. Without the app installed, the code's link opens nothing.
  • …the connection, with the right address? The phone has to reach the server. A company's internal address doesn't answer outside its network. The address must start with https://.
  • …my platform password? The credentials are the app's, not the builder's. Builders sign in to the platform in the browser.
  • …a screen that exists in the browser? Permissions are the same: a screen that account has no access to doesn't appear. Check its role in the app permissions.
  • …the app name in the phone's app list? Android shows the name the app was installed with, KeplinGo. Each app's name is on its shortcut.
  • …the home screen shortcut? The dialog was dismissed, or the launcher doesn't accept shortcuts. Ask for it again in the list, under More options ▸ Add to home screen.