Shake-to-Refresh

Shake-to-Refresh is a reusable OutSystems Mobile block that detects intentional phone movement and exposes an OnShake event. Applications can use this event to refresh lists, dashboards, notifications, offline queues, or other screen data.

Features

• Detects phone movement using the device-motion API.
• Configurable shake sensitivity.
• Cooldown protection against repeated triggers.
• Prevents duplicate listeners.
• Automatically cleans up the listener when the block is destroyed.
• Works with any refresh logic defined by the consuming application.
• Provides a manual-refresh fallback recommendation.

Requirements

• OutSystems Mobile Application.
• A physical Android or iOS device for reliable testing.
• Device-motion support enabled by the operating system/browser.
• The app must be generated and installed for final sensor testing.

Motion sensors may not work correctly in browser preview. Native device features need to be tested in a generated mobile application.

Block

ShakeToRefresh

Add the block to any mobile screen where shake detection is required.

Input Parameters

Recommended values

Enabled = True
Threshold = 18
CooldownMilliseconds = 1200
MinimumIntervalMilliseconds = 80

Sensitivity guidance:

12–16  More sensitive
18–22  Normal sensitivity
25+    Less sensitive

If the component triggers too easily, increase Threshold.

If the component does not detect a normal shake, decrease Threshold.

Events

OnShake

Triggered when the component detects a shake.

The event has no output parameters.

Example:

ShakeToRefresh.OnShake → RefreshData

The consuming application is responsible for defining the refresh behavior.

Basic Usage

1. Add the ShakeToRefresh block to a mobile screen.
2. Set the input parameters.
3. Create a client action named RefreshData.
4. Connect the block’s OnShake event to RefreshData.
5. Add a normal Refresh button and connect it to the same action.
6. Test the app on a physical device.

Example:

Phone shake
    ↓
ShakeToRefresh.OnShake
    ↓
RefreshData
    ↓
Reload screen data

Example Refresh Action

Create a client action:

RefreshData

Inside the action:

Set IsRefreshing = True
Reload data
Update screen variables
Set IsRefreshing = False

For an Aggregate-based screen, refresh the Aggregate or call the relevant data-loading client action.

For an API-based screen, call the server action that retrieves the latest data.

Lifecycle Behavior

The component starts listening when the block is initialized:

Block OnInitialize
        ↓
StartListening

It removes the sensor listener when the block is destroyed:

Block OnDestroy
        ↓
StopListening

Listener cleanup is important because it prevents:

• duplicate shake events;
• multiple refresh calls;
• memory leaks;
• unnecessary battery usage.

Supported Behavior

The component detects movement through:

window.DeviceMotionEvent

It uses the device’s acceleration values on the X, Y, and Z axes to calculate movement intensity.

A shake is triggered when the movement change exceeds the configured Threshold.

The cooldown prevents a single physical shake from generating several events.

Device Compatibility

Some iOS environments may require explicit user permission before motion data can be accessed.

Fallback Recommendation

Always provide a normal refresh button:

Refresh button.OnClick → RefreshData

The fallback is required because:

• the device may not support motion sensors;
• the user may deny permission;
• the app may be running in a browser or PWA;
• the phone may be stationary;
• shaking may not be suitable for every user.

Troubleshooting

Shake does not trigger

Try the following:

1. Test on a physical mobile device.
2. Confirm Enabled = True.
3. Lower Threshold from 18 to 14.
4. Confirm the app has motion permission.
5. Rebuild and reinstall the mobile app.
6. Confirm the block’s OnShake event is connected.

Shake triggers multiple times

Increase:

CooldownMilliseconds

For example:

CooldownMilliseconds = 2000

Also confirm that StopListening is called from the block’s OnDestroy lifecycle event.

Shake triggers too easily

Increase:

Threshold

For example:

Threshold = 22

You can also implement multi-peak detection, requiring two movement peaks within a short time window.

Works in Android but not iOS

Check:

• motion permission;
• iOS device settings;
• whether permission was requested from a user interaction;
• whether the app was rebuilt after changing native configuration.