Sign in with Google

#What connecting an account gives you

WebWatcher asks Google for one permission, the scope https://www.googleapis.com/auth/gmail.modify. Google's consent page describes it as permission to read and manage your Gmail. WebWatcher uses it only for the jobs in this table.

The narrower read-only scope cannot change labels, so the notification buttons would not work. WebWatcher requests only gmail.modify.

Google issues WebWatcher an access token and a refresh token for each account. Both are stored in the macOS Keychain, not in a file, and WebWatcher refreshes the access token when it expires. Data and privacy lists everything the app stores.

#Connect a Google account

You can start from Settings or from the email watcher editor. Both run the same sign-in.

1. Click the WebWatcher icon in the menu bar, then Settings....

   You seethe Settings window.

2. Scroll to the Gmail group and click Add Gmail Account.

   Enlarge

   You seeyour default browser opens Google's sign-in page.

3. Choose your Google account and allow the access WebWatcher asks for.

   You seea page titled "Gmail Account Connected" that says "You can close this tab and return to Web Watcher."

4. Close the browser tab and return to WebWatcher.

   You seethe account listed under Accounts with the status "Monitoring", or the unread count such as "3 unread".

   Enlarge

The sign-in must finish within 120 seconds of the browser opening, or WebWatcher stops waiting. While it waits, WebWatcher listens on a temporary port on your own Mac (127.0.0.1) so Google can send the result back to it.

To start from the editor instead, open Add Watcher, choose the Gmail sender tab and click Sign in with Google. The button appears when no account is connected yet. Once one is, the editor shows Connect another account… for adding more.

Enlarge

#Reconnect or remove an account

Reconnect when an account shows an error such as "Error: Reconnect required", or "Not connected — reconnect in Settings". A Reconnect button appears on that account's row.

1. In Settings› then Gmail, click Reconnect on the account's row.

   You seeGoogle's sign-in page in your browser.

2. Sign in with the same Google account and allow access.

   You seethe "Gmail Account Connected" page, then the row's error clears.

Signing in with a different account fails with "You signed in as ..., but this account is .... Sign in with ... instead, or add ... as a new account." Your email watchers stay attached to the mailbox they were created for.

To remove an account, click the red remove button on its row. WebWatcher deletes that account's tokens from the Keychain and stops checking it. It does not revoke WebWatcher's access on Google's side. To revoke it, open your Google Account and go to Security› then Third-party access, then remove WebWatcher.

To pause an account without removing it, turn off the switch on its row.

#Use your own Google OAuth client

WebWatcher signs in to Google with an OAuth client, a registration that identifies the app to Google. You can supply your own client when your copy of WebWatcher has none, when you build from source, or when you prefer to use your own Google Cloud project. The client you import always takes priority over a built-in one. Removing it returns WebWatcher to the built-in client, if the build has one.

#Create the client in Google Cloud Console

1. Open Google Cloud Console› then APIs & Services› then Credentials and select or create a project.

   You seethe Credentials page for that project.

2. Click Create Credentials› then OAuth client ID.

3. Set Application type to Desktop app, then click Create.

   You seea dialog with the client ID and client secret.

4. Click Download JSON.

   You seea file named client_secret_...json in your Downloads folder.

5. Open APIs & Services› then Library, find the Gmail API and click Enable.

6. Open the OAuth consent screen and choose the user type from the table below.

WebWatcher accepts only a Desktop app client. A file for a Web application client is rejected with "This is a Web application client. Create a Desktop app client instead."

#Import the client into WebWatcher

1. Open Settings› then Gmail and expand Advanced: use your own Google OAuth client.

   You seea "Google OAuth client" block with a status line, Import client JSON… and Enter manually….

2. Click Import client JSON… and choose the downloaded file.

   You seethe status line reads "Using your imported client" followed by the first 12 characters of the client ID, and a Remove link appears.

3. Click Add Gmail Account and sign in as described above.

If WebWatcher finds a client_secret...json file in your Downloads folder, the block shows "Found" and the file name with an Import button. Click it instead of choosing the file yourself. WebWatcher only reads the Downloads folder and never changes it.

To enter the values by hand, click Enter manually…, fill in Client ID and Client secret, and click Save. Save stays dimmed until the client ID ends in .apps.googleusercontent.com and the secret is not empty.

The status line at the top of the block tells you which client Add Gmail Account will use.

WebWatcher stores an imported client, including its secret, in the Keychain and never in a file. Click Remove to delete it and return to the built-in client. The block also has a How to get a client ID section that repeats the steps above.

#If it does not work