210

Geolocation and time zone data

Customer.io can gather geolocation and time zone 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 time zone data based on the IP addresses of 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.. We automatically capture IP addresses from our mobile SDKs or JavaScript client, and you can pass the context.ip field in requests to any of our other SDKs or our Pipelines API.

You can use these values to segment your audience by location or time zone. 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 time zone 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 time zone 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 time zone-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 time zone 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.

1. Go to Workspace Settings > Time Zone & Geolocation Settings.
2. Enable or disable Automatic Geolocation Data Collection.

Note that turning this setting on doesn’t:

• Enable geolocation for server-side libraries. You’ll need to enable geolocation for server-side libraries manually.
• Backfill data for existing people. You’ll need to identify people from our JavaScript client or mobile SDKs to get their geolocation data.

Enable or disable geolocation for server-side libraries

To support geolocation for server-side libraries (like our Node.JS, Go, and Python libraries), you’ll need to enable geolocation services. Then you’ll need to capture your users’ IP addresses and set them in the context.ip field in your identify requests.

1. Go to Data & Integrations > Integrations.
2. Go to your server-side integration—Node.JS, Go, or Python—and click the Settings tab.
3. Change the Enable Geolocation setting.

Capturing IP addresses for geolocation

Automatic geolocation is based on the context.ip field in identify requests. We automatically capture IP addresses from our mobile SDKs or JavaScript client.

If you use our backend libraries (like our Node.JS or Go SDKs) or our Pipelines API, you’ll have to capture the IP address yourself and pass it in the context.ip field in your identify requests. We’ve added some examples below showing the context.ip field in your identify requests to our backend SDKs.

cioanalytics.identify({
  userId: '019mr8mf4r',
  traits: {
    name: 'Cool Person',
    email: 'cool.person@example.com',
    plan: 'Enterprise',
    friends: 42
  },
  context: {
    ip: '123.45.67.89'
  }
});

func main() {
    client := analytics.New(os.Getenv("WRITE_KEY"))

    client.Enqueue(analytics.Identify{
        UserId: "user123",
        Traits: analytics.NewTraits().
            SetEmail("john@example.com").
            SetName("John Doe"),
        Context: &analytics.Context{
            IP: net.ParseIP("192.168.1.100"),
        },
    })
}

cioanalytics.identify('f4ca124298', {
    'email': 'cool.person@example.com',
    'first_name': 'cool',
    'last_name': 'person',
    'context': {
        'ip': '123.45.67.89'
    }
})

What happens to data when you disable automatic geolocation data collection?

When you disable automatic geolocation data collection, we’ll stop gathering location and time zone 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 with a context.ip field in the same request. Remember, our mobile SDKs and JavaScript client automatically capture IP addresses for you, but you’ll need to capture the IP address yourself if you use our backend libraries (like our Node.JS or Go SDKs) or our Pipelines API directly.

Even if you’ve already identified someone, additional identify requests can update a person’s geolocation data.

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.

The timezone attribute

You can set the timezone attribute (in a recognized format) to support our recommended send time feature or our time zone 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 time zone 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” time zone for people who frequently travel across multiple time zones.

When you send someone a message using a time zone-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 time zone that you set for a message. This ensures that people who don’t have time zone data still get messages.

Test your timezone attribute

If you set your time zone 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.