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:
- In the add-on's deployment
resource,
set the
addOns.common.useLocaleFromApp
field totrue
. - Add the
https://www.googleapis.com/auth/script.locale
authorization scope to the deployment resource'soauthScopes
list. This scope grants the add-on the user's permission to view their country, language, and timezone. - 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.