Using Jumpstart Pro iOS & Android with Existing Apps

API Endpoints

Your Rails API will be used for authentication and other features.

The host and URL base path are configurable in the iOS / Android app Endpoint configuration. By default, the host is http://localhost:3000 and base API uri is /api/v1. You can change this configuration to match your application's API.

When making requests to the API, you'll want to follow these rules:

• Include Android (Hotwire Native) or iOS (Hotwire Native) in the User Agent for all API requests. This tells the API the request came from Hotwire Native and should be handled accordingly.
• Use the Authorization header to authenticate user with an API token

Mobile Views

Some views will need a custom version for Hotwire Native. You can use Request Variants to accomplish this.

Hotwire includes a hotwire_native_app? helper that checks the User-Agent header for Hotwire Native. You can set the request variant for Hotwire Native requests using that.

before_action do
  request.variant = :phone if hotwire_native_app?
end

Navbar

The iOS / Android app uses a native header so it feels native. We add a hamburger button to this which triggers a Javascript event using the Hotwire Native Bridge.

In Rails, you'll want to hide your navbar on Hotwire Native requests. Use a request variant template for this so you can minimize the HTML used for mobile.

The menu should be hidden, but toggles when the toggle-nav-bar event fires. You can create a simple Stimulus Controller to listen to that event and toggle the navbar visibility.

Hotwire Native Bridge

Bridge components are how your iOS / Android app and JavaScript talk to each other. Bridge components are Stimulus controllers that can be used to do things like add native submit buttons on mobile apps so they feel more integrated. Learn more in the Hotwire Native docs.

Authentication

Authentication requires an API endpoint that accepts email and password params.

It should:

• Respond to POST /api/v1/auth
• Validate the email and password
• Sign the user in (with cookies)
• Find or create an API token for the user
• Return a 200 OK JSON response with cookies

Successful authentication will refresh the currently visible page.

Sign out

Sign out must happen on the iOS / Android app side. That way we can make an API request to remove the NotificationToken and clear cookies in the WebView.

To intercept the Sign out link in the HTML, use the following Bridge component:

import { BridgeComponent } from "@hotwired/hotwire-native-bridge"

export default class extends BridgeComponent {
  static component = "sign-out"

  static values = {
    path: String
  }

  signOut(event) {
    event.preventDefault()
    event.stopImmediatePropagation()

    const path = this.pathValue
    this.send("signOut", {path}, () => {})
  }
}

The API endpoint for Sign out needs to do two things:

• Respond to DELETE /api/v1/auth
• Delete the NotificationToken
• Sign out the current user (removing cookies)
• Returns a 200 OK response

Update Password

Changing your password is a simple API request

PATCH /api/v1/password

Headers:

• Cookie - The user's session cookie

Params:

• user[current_password] - The user's current password
• user[password] - The new password
• user[password_confirmation] - The new password

Returns:

Success - 200 OK

{ success: true }

Failure - 422 Unprocessable Entity

{ error: "Password confirmation did not match" }

Push Notifications

Registering for Push Notifications happens when the user is signed in.

The Backend needs NotificationToken model to store the token and platform for push notifications.

rails g model NotificationToken user:belongs_to platform token

An API endpoint for notification tokens should:

• Respond to POST /api/v1/notification_tokens
• Use Cookie header to authenticate user with their session cookie
• Accept params:
  • token - device notification token
  • platform - platform of device (iOS, fcm). "fcm" is Firebase Cloud Messaging which is used for Android.
• Find or create NotificationToken record for user with params
• Return 200 OK if successful

CSS

We also recommend adding class="hotwire-native" to the html or body element in your layout if hotwire_native_app? to implement styling for native apps. This is already implemented in Jumpstart Pro Rails and ready to use.