Note: We are still rolling out some features of G Suite Add-ons. You can start developing new G Suite add-ons, but may be unable to test them until the rollout is complete in early February 2020.

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—A two-letter string code indicating the user's language.
  • commonEventObject.userCountry—A two-letter string code indicating the user's country.
  • commonEventObject.userTimezone.offset—The user timezone offset, in milliseconds, from Coordinated Universal Time (UTC).
  • commonEventObject.userTimezone.id—The user's timezone identifier. For example, America/New_York.

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.