Get the locale and timezone for a Google Workspace Add-on user

This guide explains how an add-on can get a user's locale and timezone and then use that information to customize its interface and behavior. For an Google Apps Script-specific guide, see Get user locale and timezone in the Apps Script developer documentation.

Configure the add-on's deployment resource

To permit an add-on to get a user's locale and timezone, configure the add-on's deployment resource:

  1. In the add-on's deployment resource, set the addOns.common.useLocaleFromApp field to true.
  2. Add the https://www.googleapis.com/auth/script.locale authorization scope to the deployment resource's oauthScopes list. This scope grants the add-on the user's permission to view their country, language, and timezone.
  3. Save the updated deployment resource.

After adding a scope to the add-on's oauthScopes list, users must re-authorize the add-on the next time they use it.

Get locale and timezone information

Event objects include user locale information, which you can obtain from the following commonEventObject properties:

  • commonEventObject.userLocale—The user's language and country or region identifier. For example, en-US represents the English language as spoken in the United States.
  • commonEventObject.timeZone.offset—The user's timezone offset, in milliseconds, from Coordinated Universal Time (UTC).
  • commonEventObject.timeZone.id—The user's timezone identifier. For example, America/New_York.
  • commonEventObject.timeZone—The user's timezone ID and offset.

Event objects are passed to action callback functions, homepageTrigger functions, and contextualTrigger functions as the user interacts with the add-on by, for example, clicking a button. Each callback or trigger function can get the locale and timezone information from the event objects and use it as necessary. For example, a callback function that navigates to a new card could refer to the locale string when deciding what text to add to the card.