appt-org / screenreader-android

ScreenReader app for Android

Important

The appt.org website has been migrated to Docusaurus, source code is available at the appt-website repository.

Appt.org

Source code of appt.org

What is Appt?

The Appt® platform is an initiative of the Appt Foundation, a non-profit organization. Our mission is to make apps accessible for everyone. We try to achieve this by sharing free knowledge and open-source code. Appt.org is a website that empowers developers and organizations to build accessible apps for everyone.

Table of contents

• Stack
• Local development
• Environments
• Commit conventions
• Accessibility
• License

Stack

• Next.js
• Typescript
• Tailwind CSS
• Contentful
• Google Cloud Run

Local development

Local development for Appt is not supported right now. Some secrets, like API keys, are needed to make a connection with Contentful for the content of the website. For more on local development see docs on local development.

Environments

The Next.js server is hosted on Google Cloud Platform and Cloud Run as a docker container. A new version will be automatically deployed to GCP with commits on specific branches, outlined below.

Acceptance

• URL: https://appt-acceptance-o4ale4roda-ez.a.run.app
• Branch: develop

Production

• URL: https://appt.org
• Branch: main

Commit conventions

We use Conventional Commits to write clear and readable commit messages.

Accessibility

Font scaling and using REM

To make sure users that change their default font-size in the browser are still able to use Appt we make sure we support font scaling.

Don't

• Don't use fixed widths or heights on components, so the containers can grow with the font size.
• Don't use a fixed width and height on svg's.
• Don't use REM for line heights, this will result in mega line heights on Safari.

Do

• Use the viewBox on svg's with a width and height class in REM's.
• Use REM's for font sizes, paddings, margins, media queries and images that should grow when the text grows, for example logo's.

Note: We decided to not use font: -apple-system-body; for scaling text on mobile iOS devices. You can already set a default zoom level in the Safari preferences. We assume that people have this turned on. If we also turn on font scaling on iOS, users suddenly get an extra large font.

License

The source code is available under the MIT license. See the LICENSE file for more information.

screenreader-android's Issues

Detecting gestures when TalkBack is enabled

In the current version of the app (v1.0.2) the app cannot yet detect gestures when TalkBack is enabled.

One of the techniques is intercepting motion events, which works for basic gesture detection. But for advanced gestures, such as angular gestures, e.g. open the context menu, the motion events are not passed to the app.

An idea I had to overcome this, was to implement an AccessibilityService. This way, you can override the onGesture method and broadcast the gesture to the app. The implementation can be found in the ScreenReaderService file.

There are some problems with this implementation:

First: it requires users to enable the service through the accessibility settings of their device. This is a complex series of steps. I have tested this with users, and for most it was too difficult and/or scary to do.

Secondly: there are potential bugs which cause the device to "brick". This can happen because the ScreenReaderService receives all the gestures, but doesn't perform any actions upon receiving them. The service should de-activate itself when the gesture training is inactive, but this doesn't work with 100% confidence on all Android devices.

For the second issue, I looked into the new setGestureDetectionPassthrough method which was added in Android API 30. It looked promising, but I did not manage to get it to work. I did not notice different behavior compared to not setting a passthrough region.

I hope others have more idea's to recognize gestures when TalkBack is active.

Fix review pop-up

Hi Jan Jaap, ik heb de app vorige week met 6 studenten gebruikt (2 op iOS en 4 Android) en ze klaagden allemaal dat de app na élke stap vraagt of je een positieve review wil achterlaten, ook als ze de app nog maar een minuut hadden gebruikt. Het heeft ze niet aangemoedigd om een review achter te laten 
De app zelf is wel heel erg fijn om met studenten te gebruiken!

Text editing lessons need updating

The lessons on selecting, copying, and pasting text seem to be somewhat out of date with recent TalkBack releases.

There's no longer an "Editing options" item in the TalkBack context menu. Instead, there's an "Actions" item which holds text editing options, but that item is contextual so it won't always be present.

(I found this somewhat confusing, as it meant that if I had only focused the text control, "Actions" wasn't one of the menu options. I had to make sure I was editing the text inside the control -- the edit cursor was enabled -- in order to have the "Actions" option in the TalkBack menu.)

Update shortcut documentation for recent releases?

The app currently provides instructions for setting up a TalkBack shortcut via the Accessibility shortcuts settings:

https://github.com/appt-org/screenreader-android/blob/main/app%2Fsrc%2Fmain%2Fres%2Fvalues%2Fstrings.xml#L58-L61

While those instructions do still work, recent Android releases have dedicated TalkBack settings that may provide clearer explanations and additional options.

If the user instead goes to Settings > Accessibility > TalkBack > TalkBack shortcut, they'll find not only a switch to enable/disable a shortcut, but they can tap on the setting item to view a dedicated menu listing all of the shortcut assignment options.

For sighted users only using TalkBack for testing purposes, placing the shortcut on the navigation bar ("Accessibility button") may be more convenient than assigning a hardware button shortcut.

Perhaps the app should either recommend that option, instead of the volume keys, or at least note that there are several options for what shortcut to assign?