Skip to main content

Import additional person data for your visitors

It’s possible to import an extended set of person data into Fresh Relevance.

Updated over a month ago

Before you start

Things you need to know:

  • You must first understand how to import basic person data.
    Learn more in Import person data.


Extended person data sets

You can import any fields you want into person.extend along with the following top-level person fields:

  • person.n - full name

  • person.fn - first name

  • person.ln - last name

For example, you could import something that you know about the individual to person.extend.favorite_color:

email                                firstname   lastname   favorite_color
test.test@triggeredmessaging.com Joe Bloggs orange

To make this import correctly, you must use a channel with a field mapping like this:

{
"email": {
"ftp_field_name": "email"
},
"person.fn": {
"ftp_field_name": "firstname"
},
"person.ln": {
"ftp_field_name": "lastname"
},
"person.extend.favorite_color": {
"ftp_field_name": "favorite_color"
}
}

As a more sophisticated import example, you can also import JSON structures, for example:

  • A list of values within a field

    email                                 my_field
    test.test@triggeredmessaging.com ["cars","bikes"]
  • A dictionary of fields and values within a field

    email                                 my_field
    test.test@triggeredmessaging.com {"cars":"two","bikes":"three"}

To make this import correctly, you would need to use a channel with a field mapping like this:

{
"email": {
"ftp_field_name": "email"
},
"person.extend.my_field": {
"ftp_field_name": "my_field",
"field_type": "json"
}
}

Customer groups for multiple price books

Requires the B2B module.

A customer group is a code which defines which set of prices are seen by each person.

Several prices are imported for the products, for example:

  • Base price:£26.99

    • groupA: £23.99

    • groupB: £24.99

    • groupC: £25.99

These prices are imported into the product, and a corresponding code is imported to the field person.cg, to tell the system that that person should see the price for their customer group.

For example:

email                  firstname  lastname  favorite_color  customer_group
test.test@example.com Joe Bloggs orange VIP

To make this import correctly, you must use a channel with a field mapping like this:

{
"email":{"ftp_field_name":"email"},
"person.fn":{"ftp_field_name":"firstname"},
"person.ln":{"ftp_field_name":"lastname"},
"person.extend.favorite_color":{"ftp_field_name":"favorite_color"}
"person.cg":{"ftp_field_name":"customer_group"}
}

Assign a SmartBlock to imported people records

To use the Show Assigned SmartBlock rule in Slots, you must upload SmartBlock IDs formatted like this:

EmailAddress               test-slot-1    test-slot-2
test.test@example.com xlkjl3 oiuklj3

To make this import correctly, you must use a channel with a field mapping like this:

{
"email": {
"ftp_field_name": "EmailAddress"
},
"person.content.keys.test-slot-1": {
"ftp_field_name": "test-slot-1"
},
"person.content.keys.test-slot-2": {
"ftp_field_name": "test-slot-2"
}
}

Import a fixed value for every person

Fixed values can be imported using the val attribute in the field mapping.

Here’s an example of a field mapping which sets every imported person to have ex.imported set to yes:

{
"email": {
"ftp_field_name": "EmailAddress"
},
"person.extend.imported": {
"val": "yes"
}
}

Import location data

You can upload a visitor’s location for use by location-based Slot rules. This can provide more accurate locations for your known customers.

Location upload requires either:

  • The postal / zip code and the country code.
    The country code must be a two letter upper case ISO 3166-1 Alpha-2 country code, for example GB, FR, US, AU.

  • The visitor's latitude and longitude.

Example CSV file

EmailAddress,Country,Postcode
test_uk@example.com,GB,SW1A 1AA
test_us@example.com,US,20500

To make this import correctly, you must set the channel's import field mapping to:

{
"email": {
"ftp_field_name": "EmailAddress"
},
"location": {
"location_type": "postcode",
"country_code_field_name": "Country",
"postcode_field_name": "Postcode"
}
}

Example CSV file that would import the location for two shoppers using latitude and longitude

EmailAddress,latitude,longitude
test_uk@example.com,-1.4304542541503906,50.962339396267446
test_us@example.com,-0.07894277572631836,51.50027116593512

To make this import correctly, you must set the channel's import field mapping to:

{
"email": {
"ftp_field_name": "EmailAddress"
},
"location": {
"location_type": "latlng",
"latitude_field_name": "latitude",
"longitude_field_name": "longitude"
}
}

By default, the imported location data is used by Slot rules for 1,000 days. You can use IP-based geolocation, when available, in Slot rules, or change how long the imported location can be used, under Location Settings.

Learn more in Use Geotargeting.

Import location data from your location sets

Location IDs, for example, a store, region or airport, from within a location set can be associated with a visitor based on an import.

The nearest location within the set is picked, up to a configurable maximum distance, or based on a defined region around the location. This could be useful to pick, for example, the nearest store to each shopper, unless they are more than 20km away from a store.

Supplying the location you want to add from a location set allows you to import a fixed location ID for customers, for example, if you know which their preferred store is - even if it’s not the geographically nearest location.

Example CSV file

EmailAddress,Country,Postcode,local_store_country,local_store_postcode
test_uk@example.com,GB,SW1A 1AA,GB,SE1 3JB

To make this import correctly, you must set the channel's import field mapping to:

{
"email": {
"ftp_field_name": "EmailAddress"
},
"location_ids": {
"location_type": "postcode",
"country_code_field_name": "local_store_country",
"postcode_field_name": "local_store_postcode",
"location_sets": "template:uk-cities|mystores",
"list_separator": "|",
"max_distance": 10000
},
"location": {
"location_type": "postcode",
"country_code_field_name": "Country",
"postcode_field_name": "Postcode"
}
}

Example CSV file that would import additional location IDs as well as the visitor's location for using latitude and longitude

EmailAddress,latitude,longitude,local_store_latitude,local_store_longitude
test_uk@example.com,-1.4304542541503906,50.962339396267446,-0.07894277572631836,51.50027116593512

To make this import correctly, you must set the channel's import field mapping to:

{
"email": {
"ftp_field_name": "EmailAddress"
},
"location_ids": {
"location_type": "latlng",
"latitude_field_name": "local_store_latitude",
"longitude_field_name": "local_store_longitude",
"location_sets": "template:uk-cities|mystores",
"list_separator": "|",
"max_distance": 10000
},
"location": {
"location_type": "latlng",
"country_code_field_name": "latitude",
"postcode_field_name": "longitude"
}
}

Example CSV file that would import additional locations by providing the location IDs

email,id,first_name,gender,discounted,store
test17815a@example.com,11111,Jim,m,20%,southampton

To make this import correctly, you must set the channel's import field mapping to:

{
"email": {
"ftp_field_name": "EmailAddress"
},
"location_ids": {
"mapped_location_sets": {
"mystores": "store"
}
},
"location": {
"location_type": "latlng",
"country_code_field_name": "latitude",
"postcode_field_name": "longitude"
}
}

Using mapped_location_sets takes preference and overwrites any resolved values; latLng or postcode.


Import a wishlist with a person import

The wishlist data source shows products that the current person has added to their wishlist on another system. The wishlist is then imported into Fresh Relevance and is stored in the field person.extend.wishlist.

The import is driven by a person import file which contains a JSON structure containing product IDs along with quantities and date added.

Here's an example of a wishlist structure for one person, containing two products that they have on their wishlist. It must be imported into the field person.extend.wishlist, and the product IDs must match with the product IDs in the Fresh Relevance database.

{
"product_id1": {
"qty": 1,
"dt": "2014-01-01T12:13:14Z"
},
"product_id2": {
"qty": 1,
"dt": "2014-01-01T12:13:14Z"
}
}

An example field mapping for import might be:

{
"email": {
"ftp_field_name": "email"
},
"person.extend.wishlist": {
"ftp_field_name": "wishlist_data"
}
}

An example CSV import file, for one person, might look something like this:

email                         wishlist_data
first.last@example.com {"prid1": {"qty": 1, "dt": "2014-01-01T12:13:14Z"},"prid2": {"qty": 1, "dt": "2014-01-01T12:13:14Z"}}

Wishlist structure with variants

It’s also possible to import an SKU-level product variant into a wishlist by adding the variant's ID in the vid field:

{
"product_id1": {
"vid": "small",
"qty": 1,
"dt": "2014-01-01T12:13:14Z"
},
"product_id2": {
"vid": "medium",
"qty": 2,
"dt": "2014-01-01T12:15:14Z"
}
}

To add multiple variants of the same product you can also include an array of different variants to add:

{
"product_id1": [
{
"vid": "small",
"qty": 1,
"dt": "2014-01-01T12:13:14Z"
},
{
"vid": "medium",
"qty": 2,
"dt": "2014-01-01T12:15:14Z"
}
]
}

Advanced: Encryption

You can encrypt the data being sent to Fresh Relevance using GPG encryption. To do this, you must import our public key into your GPG software.

This is the key certificate, which you should save into a text file with a .cer extension:

Key certificate

-----BEGIN PGP PUBLIC KEY BLOCK-----

Version: GnuPG v1
mQENBFVfMdYBCAC29By8jNAs022YGwSVOUT9xSv+dVMOVnAjcskwrs65ZgyXY+3C
8wWnCOR0A6ZewYVp4A79gTstdarJywG1z555hoNSxMFQWv5mPp1RseX9hmqfks2a
l3FFdCCyja8iaCVDGTXtEuls4qRH0gJIkDi0h3jH5jtr0mK921N1rzXUTi1W+FEO
tC5yXsIBEkPS2ZO+kyewjLcckA2P0Yi3Xacq+3+zmGE+czZkiYxWW4uiKZ0gVAmV
jmerpSg2EH967jI7gkcp6C2eKToLfv57n19CbFND/mLPph1intXJMa5ZGCOEtbbV
ak0tzLaYBZrHNgOw5wj8A9adJY6ipEy6apNbABEBAAG0MEZyZXNoIFJlbGV2YW5j
ZSBMdGQgPHN1cHBvcnRAZnJlc2hyZWxldmFuY2UuY29tPokBOAQTAQIAIgUCVV8x
1gIbAwYLCQgHAwIGFQgCCQoLBBYCAwECHgECF4AACgkQh0e3Iz5EaWLQ5wgAsEIh
IhLF7LNeY9myd/8J0d31kaOxnXreEVfx+tknA9B8YXZfdFC3nCA3FcyggxgOFUP2
jR8z8N5/gs7Pv8CGz420usOLZQBleGn+swuEasPkipay5sQQYQUtzdiGUt0aWRJG
7B/GaZt1wD349p/uep8YuHpiiemNN1BuHg+I6s17va3p82dRFC4ZNLGoa/O4qKsD
1+OAqao3m6a98RfU1J1zOgz4PDSYSe+bqROtyqLRBMs0qPXTjreqYdd3G9u1L8wF
N8Ly8odPhp7ECDoXhT+Rjm8merGfSjDXRIOgPdmsPg+87dQNDmpIbHreEYXbduzS
4hbq2oEm6uv5uvF3RrkBDQRVXzHWAQgA2O60SZX5gUiskT09w2rtRX+WItP9UG8j
XWtj+mrLBobEqLQF9G0uu8IouxBX4cp1/Ca43/MZb45LUmcG+xHoiCWTYGaQHP5t
bYpySim4GOvvh6ej2IScj+ujmqcMH6octrO3Z0ldgGXbVv8Rvz0Kw4fDF+xJzzhl
u2ZLpr1S+QIdNHEzDyBAq5LQk0w14VLZbIkfK6cumW6aVk2EPylTePa3F2sc6Bhx
O8n2E7IcnPmxiTfD+1IzrsGcDWIFiwRA8z+LkBcDPwH01z0Bs07TZrRLVrWiERNv
MUDoGWeqgQ+3sXhegiy3mYx0wo0VAys3lPMR/daXWp7lU8WgCQOakQARAQABiQEf
BBgBAgAJBQJVXzHWAhsMAAoJEIdHtyM+RGliOB8H/RzHKygJOX6L1wNWwn3HaXOu
RkRF2RvcZaLB/9q6gTqwclpAw8QdU66mcNYiGDi/MI9r70LKrGrTPUEdRsSdbEBI
45FIz/JbCw+cQRh80zkTVl5aFKeNACRlkgVMg0U/hVD+oqSKKnOKYXKbe0uGzXWu
MRHpCFiTxNACLWR/vX/5hJztzO2qteGsshbp6IedIGD3DMzKHrBDfuCQE+AUho1K
LiEab9mmVhQ9KcLmSkQfeL7FiVcMcXlya2sadzSRHBFdtIMorzX6USU9+KLvo8DD
S5OpU17SlWEMNUmB2UAuApo0AOOuvT515yXoIzw4cTsWb2yw5xdamk3meOlGLjw=
=Oth0

-----END PGP PUBLIC KEY BLOCK-----

Did this answer your question?