Update Management

Update Management APIs allows your mini app to detect a new version and restart at an appropriate time when the update is ready. The TikTok app checks for updates automatically. Call window.TTMinis.getUpdateManager() to obtain the global update manager.

How it works

When a user opens the mini app, the TikTok app automatically checks whether a new version is available. Developers do not need to, and cannot, manually start this check. When the check finishes, onCheckForUpdate fires. If a new version exists, the TikTok app prepares it and then fires either onUpdateReady when it can be applied or onUpdateFailed if preparation fails.

Integration example

Register listeners at the application entry point, before route initialization, or in another location that runs only once.

function setupUpdateManager() {
  if (typeof window.TTMinis === 'undefined' || typeof window.TTMinis.getUpdateManager !== 'function') {
    console.warn('UpdateManager is not supported');
    return;
  }

  const updateManager = window.TTMinis.getUpdateManager();

  updateManager.onCheckForUpdate((res) => {
    console.log('version check finished:', res.hasUpdate);
  });

  updateManager.onUpdateReady(() => {
    const confirmed = window.confirm(
      'A new version is ready. Restart and update now?'
    );
    if (confirmed) {
      // Persist playback progress and other app state first.
      updateManager.applyUpdate();
    }
  });

  updateManager.onUpdateFailed(() => {
    console.warn('new version could not be prepared');
  });
}

setupUpdateManager();

API reference

TTMinis.getUpdateManager

Synchronously returns the global UpdateManager instance. This method takes no parameters.

const updateManager = window.TTMinis.getUpdateManager();

Return value: An UpdateManager object. Repeated calls in the same JavaScript runtime return the same object.

updateManager.onCheckForUpdate

Registers a callback that runs when a version check finishes. The callback receives an object with the following property:

updateManager.onCheckForUpdate((res) => {
  console.log(res.hasUpdate);
});

This method returns no value. Registering a listener does not start another version check.

updateManager.onUpdateReady

Registers a callback for when the new version is ready. After this event fires, call applyUpdate() to apply the version. The callback takes no parameters, and the method returns no value.

updateManager.onUpdateReady(() => {
  console.log('update is ready');
});

updateManager.onUpdateFailed

Registers a callback for a failure to prepare the new version, such as a failure to retrieve update resources. The callback takes no parameters, and the method returns no value. Keep the current version running and wait for the TikTok app to check again during a later launch.

updateManager.onUpdateFailed(() => {
  console.warn('update failed; keep using current version');
});

updateManager.applyUpdate

Applies the ready version and immediately restarts the current mini app. This method takes no parameters, returns no value, and does not accept success, fail, or complete callbacks.

updateManager.applyUpdate();

Call applyUpdate() only after onUpdateReady fires. Persist playback progress and any other recoverable application state before calling it.

Timing and listener behavior

• Register early: Register all three callbacks at the application entry point to observe the complete check, ready, or failed sequence. Do not wait until a user opens a settings page or taps a “Check for updates” control.
• Register each callback once: Avoid registering callbacks repeatedly from page initialization or component mounting logic, because the same event may otherwise trigger duplicate application handling.

Recommended user experience

When onUpdateReady fires, tell the user that a new version is ready and let them choose whether to restart immediately. Do not automatically call applyUpdate() while content is playing, a form is being completed, or a payment is in progress. After the user confirms, persist recoverable state before applying the update.

When onUpdateFailed fires, do not block the current version. Record the failure if needed and continue serving the user. The TikTok app can check again during a later launch cycle.

Compatibility and troubleshooting