NativeAppTemplate-Free-iOS

May 2, 2026 · View on GitHub

NativeAppTemplate-Free-iOS is a modern, comprehensive, and production-ready native iOS app with user authentication and background tag reading.
This iOS app is a free version of NativeAppTemplate-iOS (Solo) and NativeAppTemplate-iOS (Team).

The Android version is available here: NativeAppTemplate-Free-Android.

Overview

NativeAppTemplate-Free-iOS is configured to connect to api.nativeapptemplate.com.
The Rails 8.1 API backend that powers api.nativeapptemplate.com is open source (MIT):

Screenshots

Screenshot showing Sign in screen, Shops screen and Settings screen

Features

NativeAppTemplate-Free-iOS uses modern iOS development tools and practices, including:

Included Features

  • Onboarding
  • Sign Up / Sign In / Sign Out
  • Email Confirmation
  • Forgot Password
  • CRUD Operations for Shops (Create/Read/Update/Delete)
  • CRUD Operations for Shops' Nested Resource, Item Tags (Create/Read/Update/Delete)
  • Force App Version Update
  • Force Privacy Policy Version Update
  • Force Terms of Use Version Update
  • And more!

NFC Tag Operations

How NFC tag writing and background reading works

Overview

Screenshot showing Overview before

Screenshot showing Overview after

The app replaces traditional paper tags with NFC tags to efficiently manage walk-in customer waitlists. It writes application-specific information onto your NFC cards (referred to as :red_circle: Server Tag and :large_blue_circle: Customer Tag).

For Customers:
When a customer scans a :large_blue_circle: Customer Tag, they can view the :green_circle: Number Tags Webpage (a public webpage) on their mobile browser. This page displays completed Number Tags.

For Staff:
By scanning a :red_circle: Server Tag paired with the :large_blue_circle: Customer Tag, staff can complete a Number Tag. Completed Number Tags automatically appear on the :green_circle: Number Tags Webpage for customer reference.

How It Works

Screenshot showing Write Application Info to Tag screen, Scan Tag screen, and Shop Detail screen

  1. Write application info to pair Number Tags (Server Tag and Customer Tag) or a Customer QR code:
    • Go to: Shops > [Shop] > Shop Settings > Manage Number Tags > [Number Tag].
  2. Scan a Server Tag in the Scan tab.
  3. View the updated Number Tags status in the Shop Detail screen or on the Number Tags Webpage (see Background Tag Reading GIF below).

For best performance, use NTAG215 (540 bytes) tags.
Example: 50pcs NFC Cards Ntag215 (Amazon USA).

Background Tag Reading

Gif showing Background Tag Reading

  1. Scan a Server Tag.
  2. View the updated Number Tags status in the Shop Detail screen or on the Number Tags Webpage.

The Number Tags Webpage updates in real-time using Rails Turbo.
This functionality is part of the open-source nativeapptemplateapi backend.

Note:
The GIF above shows MyTurnTag Creator for iOS in action, which may behave slightly differently from NativeAppTemplate-Free-iOS.

Associated Domains Requirement (iOS)

For background tag reading to work correctly on iOS, you must configure Associated Domains in your app.

To set up Associated Domains on iOS, follow these steps:

  1. Add your domain (e.g., applinks:api.example.com) to the Associated Domains section in Xcode under Signing & Capabilities.

  2. Configure the apple-app-site-association (AASA) file and host it on your server.

  3. Verify that the AASA file is correctly configured and accessible by checking its contents at the following URL:

    🔗 https://app-site-association.cdn-apple.com/a/v1/api.example.com

  4. Uninstall NativeAppTemplate-Free-iOS, reset your device, and then reinstall NativeAppTemplate-Free-iOS to ensure the changes take effect.

For detailed instructions, refer to Apple's official documentations:

Not Included in the Free Version

Gif showing Switching organization

The full versions (NativeAppTemplate-iOS (Solo) and NativeAppTemplate-iOS (Team)) include additional advanced features:

  • URL Path-Based Multitenancy (prepends /:account_id/ to URLs)
  • User Invitation to Organizations
  • Role-Based Permissions and Access Control
  • Organization Switching UI

Supported Devices

  • iPhone — iOS 26.2+, Portrait mode, Full screen
  • iPad — iOS 26.2+, Portrait mode, Full screen
  • Mac — Designed for iPad

Getting Started

To get started, clone this repository:

git clone https://github.com/nativeapptemplate/NativeAppTemplate-Free-iOS.git

Requirements

To run this app successfully, ensure you have:

  • An iOS device or emulator with iOS version 26.2 or higher

Running with the NativeAppTemplate-API on localhost

To connect to a local API server, set these env vars on the Xcode scheme (Edit Scheme → Run → Arguments → Environment Variables):

NATIVEAPPTEMPLATE_API_SCHEME = http
NATIVEAPPTEMPLATE_API_DOMAIN = <your-lan-ip>
NATIVEAPPTEMPLATE_API_PORT   = 3000

Note: Never use 127.0.0.1, localhost, or 0.0.0.0 for NATIVEAPPTEMPLATE_API_DOMAIN — those resolve to the iOS Simulator/device itself, not your Mac. Use your Mac's LAN IP (e.g., 192.168.1.6) so the simulator or a physical device can reach the API server.

Keep the scheme in xcuserdata (per-developer, gitignored), not xcshareddata. In Xcode, open Product → Scheme → Manage Schemes…, find NativeAppTemplate, and uncheck "Shared". This moves the scheme (with your local env vars) to xcuserdata/<user>.xcuserdatad/xcschemes/ so your API settings are not committed. If Xcode staged a deletion of the previously shared scheme, restore it with:

git restore --source=HEAD --staged --worktree NativeAppTemplate.xcodeproj/xcshareddata/xcschemes/NativeAppTemplate.xcscheme

Debug builds read these at launch via ProcessInfo.processInfo.environment in Constants.swift; when unset, they fall back to the production defaults (https://api.nativeapptemplate.com). Release builds always use the production defaults.

In practice, only Xcode injects these env vars (via the scheme), so a Debug build launched any other way — tapped from the Home Screen (SpringBoard), opened on a physical device after Xcode disconnects, etc. — sees them unset and falls through to the production defaults. The hardcoded fallbacks are what keep the app working without Xcode in the loop.

SwiftLint

SwiftLint runs as part of the build process in Xcode, and errors/warnings are surfaced in Xcode as well. Please ensure that you run SwiftLint before submitting a pull request.

To install SwiftLint using homebrew:

$ brew install swiftlint

Xcode will automatically run SwiftLint if it is installed.

Blogs

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on reporting issues, proposing changes, and submitting pull requests.

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Security

If you discover a security vulnerability, please follow the disclosure process in SECURITY.md. Do not open public issues for security concerns.

License

This project is licensed under the MIT License — see LICENSE for details.