Geolocation and timezone data
UpdatedCustomer.io can gather geolocation and timezone data from your audience, helping you coordinate messages at times that are appropriate for them.
How it works
If you use our Automatic Geolocation Data Collection feature, we’ll automatically infer location and timezone data from people you identifyThe Customer.io operation that adds or updates a person. When you identify a person, Customer.io either adds a person if they don’t exist in your workspace, or updates them if they do. Before you identify someone (by their email address or an ID), you can track them anonymously. from our mobile SDKs or JavaScript client based on their IP addresses.
You can use these values to segment your audience by location or timezone. You can also use time zone data to send messages at the right time for your audience with our recommended send time feature or our timezone match features.
You can also set a timezone attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. to support our time zone-related features. You might set this value if you don’t use automatic geolocation data collection and you want to support recommended send time or timezone match features.
The timezone attribute takes precedence over the cio_timezone attribute we set when automatic geolocation data collection is enabled, ensuring that we don’t disrupt any timezone-related data that you’ve already collected (or collected independently of automatically-collected geolocation data).
Enable or disable automatic geolocation data collection
Enabling Automatic Geolocation Data Collection lets us gather location and timezone data for people you identify based on their IP addresses. This setting is on by default in our US data center. If you’re in our EU data center, you’ll need to enable it manually.
- Go to Workspace Settings > Time Zone & Geolocation Settings.
- Enable or disable Automatic Geolocation Data Collection.
Note that turning this setting on doesn’t backfill data for existing people. You’ll need to identify people from our JavaScript client or mobile SDKs to get their geolocation data.
Supported SDKs
We support automatic geolocation data with any of our mobile SDKs or JavaScript client. These SDKs collect the IP addresses of clients, which we use to gather location and timezone data.
What happens to data when you disable automatic geolocation data collection?
When you disable automatic geolocation data collection, we’ll stop gathering location and timezone data for people you identify. You can also choose to delete existing geolocation data for people you’ve already identified.
If you disable automatic geolocation data collection, there’s no harm in keeping this data around. But it might clutter profiles if you don’t use this data.
We geolocate people when you identify them
We don’t add or update geolocation data until you identifyThe Customer.io operation that adds or updates a person. When you identify a person, Customer.io either adds a person if they don’t exist in your workspace, or updates them if they do. Before you identify someone (by their email address or an ID), you can track them anonymously. someone using our JavaScript client or mobile SDKs—based on the context.ip field that these data sources automatically capture in requests.
We’ll update location and timezone attributes whenever you identify them again.
context.ipin the request?} a--->|Yes|b(Update geolocation data) a-.->|No|c(Do not update geolocation data)
Identify people in new sessions to keep geolocation data up to date
Your website and mobile app might “remember” users across sessions. But, even if you don’t need to update any information about them, you should identify them again in a new session to keep their geolocation data up to date. This can help you keep up with people as they move around the world.
Automatic geolocaiton attributes
When you enable automatic geolocation data collection, we will automatically capture the following attributes when you identifyThe Customer.io operation that adds or updates a person. When you identify a person, Customer.io either adds a person if they don’t exist in your workspace, or updates them if they do. Before you identify someone (by their email address or an ID), you can track them anonymously. someone.
You shouldn’t set these attributes yourself. If you do, it’s likely that we’ll overwrite your data with our own values whenever you identify a person.
| Attribute | Description |
|---|---|
cio_iso_country | The user’s ISO country code in alpha-2 format (like “US”). |
cio_country_name | The user’s country name in ISO 3166-1 format (like “United States”). |
cio_city | The user’s city name. |
cio_latitude | The latitude of the user’s city. |
cio_longitude | The longitude of the user’s city. |
cio_timezone | The user’s time zone. This is the value we use for recommended send times. |
The timezone attribute
You can set the timezone attribute (in a recognized format) to support our recommended send time feature or our timezone match features. This attribute takes precedence over our cio_timezone attribute. You should set it if:
- You don’t use automatic geolocation data collection and you want to support recommended send times or timezone match features.
- You have one or more integrations that don’t support automatic geolocation data collection—like our Node.JS or Go SDKs.
- You want to set a “home” timezone for people who frequently travel across multiple time zones.
When you send someone a message using a timezone-related feature, we’ll use the timezone attribute if it exists and conforms to our supported formats. If it doesn’t exist, we’ll use the cio_timezone attribute as a fallback.
If the timezone and cio_timezone attributes don’t exist, we’ll use the fallback timezone that you set for a message. This ensures that people who don’t have timezone data still get messages.
timezoneattribute exist?} a--->|Yes|b(Send message in
customer timezone) a-.->|No|c{Does
cio_timezoneattribute exist?} c-->|Yes|b c-.->|No|d(Send message in
fallback timezone)
Test your timezone attribute
If you set your timezone attribute manually, you can test it to make sure that you’re using a format we support.
Go to Workspace Settings > Advanced: Time Zone Match.
Enter the id or email address of a person in your workspace, and we’ll tell you if the timezone attribute is in the correct format.
