> For the complete documentation index, see [llms.txt](https://help.twinr.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.twinr.dev/screens/login/general.md).

# General

Turn login on, choose when customers must sign in, and tell Twinr how to recognise a signed-in customer.

Your app signs customers in using **your website's own login page**. Twinr does not replace it or store any credentials — it opens your sign-in form inside the app and watches the page to work out whether the customer is signed in.

That is why this screen needs a short script from you. Your site already knows who is signed in; this tells Twinr how to read that.

## The three toggles

<figure><img src="https://3731994945-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlBy5z08zL1UoCwNqmg%2Fuploads%2Fgit-blob-da36d771f4afbc149289db7770c20ea85e3ecf68%2Flogin-general.png?alt=media" alt="The Customer login card with three toggles: enable login, require login at the start, and keep users logged in"><figcaption></figcaption></figure>

<table><thead><tr><th width="290">Toggle</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Enable login process</strong></td><td>The master switch. With it off, nothing else on this screen applies and your app has no sign-in step.</td></tr><tr><td><strong>Require login at the start</strong></td><td>On: customers see the sign-in screen before anything else. Off: they can browse, and are asked to sign in only when they reach something that needs it.</td></tr><tr><td><strong>Keep users logged in</strong></td><td>On: customers stay signed in between visits. Off: they sign in each time they open the app.</td></tr></tbody></table>

{% hint style="info" %}
**Think about which one your app needs.** Requiring login at the start suits a members-only app or a portal where nothing is public. A shop usually wants it off — making people sign in before they can see a single product costs you customers who would have browsed first.
{% endhint %}

**Keep users logged in** should almost always be on. Signing in on a phone is tedious, and an app that forgets you every time feels broken.

## Login status check script

This is the part that does the real work. Twinr runs your script against the page and expects it to return one of four statuses:

| Status        | Meaning                                             |
| ------------- | --------------------------------------------------- |
| `loggedIn`    | The customer is signed in. Twinr lets them through. |
| `notLoggedIn` | They are not signed in.                             |
| `authError`   | They tried to sign in and the details were wrong.   |
| `unknown`     | Nothing matched. Use this as your fallback.         |

The names must match exactly.

### How to write it

Each status is a selector that only exists on a page in that state. Open your site in a desktop browser and use the inspector to find one:

1. **`notLoggedIn`** — something unique to your sign-in page, usually the form itself.
2. **`loggedIn`** — something that only appears once signed in, such as a sign-out link or an account menu.
3. **`authError`** — the error message shown after a failed attempt.

Here is a real example:

{% code lineNumbers="true" %}

```javascript
if (document.querySelector('.error') || document.querySelector('.alert')) {
  'authError'
} else if (document.querySelector('#inbox-link')) {
  'loggedIn'
} else if (
  document.querySelector('#email') ||
  document.querySelector('a[href*="/login"]')
) {
  'notLoggedIn'
} else {
  'unknown'
}
```

{% endcode %}

{% hint style="warning" %}
**Do not copy this script as-is.** The selectors are from one particular site. Yours will be different, and a script with the wrong selectors leaves every customer stuck at the sign-in screen.
{% endhint %}

**Check the error case carefully.** Sites often use different messages for a wrong password, an unknown email, and a locked account. Cover them all with `||`, or a customer who mistypes their password sees nothing happen:

```javascript
if (
  document.querySelector('#username-error') ||
  document.querySelector('#password-error') ||
  document.querySelector('.alert-danger')
) { 'authError' }
```

### Test it before you save

Open your site in a desktop browser, paste the script into the developer console, and check it returns the right status. Then sign in and run it again — it should change to `loggedIn`. Finally, try a wrong password and confirm you get `authError`.

If it returns the right value in all three states, it will work in the app.

## Login page selectors

Twinr needs to find the parts of your sign-in form so the app can work with it.

<figure><img src="https://3731994945-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlBy5z08zL1UoCwNqmg%2Fuploads%2Fgit-blob-9ef9fd9538df6d2984cbf21385f1700d1c870dcc%2Flogin-selectors.png?alt=media" alt="The Login Page Selector card with fields for login form, submit button, username field and password field"><figcaption></figcaption></figure>

| Field                       | What to enter                                        |
| --------------------------- | ---------------------------------------------------- |
| **Login form selector**     | The `<form>` element that holds your sign-in fields. |
| **Submit button selector**  | The button that submits it.                          |
| **Username field selector** | The email or username input.                         |
| **Password field selector** | The password input.                                  |

Prefer an `id` such as `#email` over a class — class names change when your theme is updated, and a changed class quietly breaks sign-in for everyone.

Click **Save as draft** when you are done.

## Common Questions

<details>

<summary>Does Twinr see my customers' passwords?</summary>

No. The sign-in happens on your own website inside the app's web view, exactly as it does in a browser. Twinr only reads whether the page indicates a signed-in state.

</details>

<details>

<summary>My customers reach the sign-in screen and nothing happens.</summary>

Almost always the status script. Run it in your browser console on the signed-in page — if it does not return `loggedIn` there, the app cannot know the customer got in.

</details>

<details>

<summary>Sign-in broke after I updated my website.</summary>

Your selectors probably changed. Re-check each one against the live page, especially if they were class names rather than IDs.

</details>

<details>

<summary>Can I use Google or Apple sign-in instead?</summary>

Those are separate features with their own setup, independent of this web-based login.

</details>