Accessing user locale and timezone

Add-ons can access the locale and timezone of its user and the use that information to customize its interface and behavior. You must configure your add-on's manifest to permit your add-on to access this information.

Configure the add-on manifest

You can configure your add-on to access user locale and timezone information with the following steps:

  1. In your add-on's manifest file, set the addOns.common.useLocaleFromApp field to true.
  2. If it isn't present already, add the following explicit scope in the manifest's oauthScopes list: https://www.googleapis.com/auth/script.locale
  3. Save the manifest changes.

If you added a scope to the add-on's oauthScope list, users must re-authorize the add-on the next time it is opened.

Obtaining locale and timezone information

Event objects carry user locale information when properly configured. The following fields appear in the commonEventObject substructure of the event object:

  • commonEventObject.userLocale—The user's language and country/region identifier. For example, en-US.
  • 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.

See Event objects for more details.

Event objects are passed to action callback functions as the user interacts with your add-on, and to homepage and contextual trigger functions. Each callback or trigger function can read the locale and timezone information from the event object and use it as necessary. For example, a callback function that is navigating to a new card could refer to the locale string when deciding what text to add to the card.