{"__v":9,"_id":"575e15b28adab20e00b5fa59","category":{"__v":3,"_id":"55e67aac9cc7c62b00c4a1ee","pages":["55e67aae9cc7c62b00c4a1f0","55e67bfd9cc7c62b00c4a1f5","55ecd59b54a67b1700edcf3c"],"project":"55e67aaa9cc7c62b00c4a1ea","version":"55e67aab9cc7c62b00c4a1ed","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-02T04:27:24.277Z","from_sync":false,"order":0,"slug":"getting-started","title":"Getting started"},"parentDoc":null,"project":"55e67aaa9cc7c62b00c4a1ea","user":"55d29988486de50d00327118","version":{"__v":10,"_id":"55e67aab9cc7c62b00c4a1ed","project":"55e67aaa9cc7c62b00c4a1ea","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["55e67aac9cc7c62b00c4a1ee","55e67b5556007d23005fee7d","55e67b5dde6fef23009480ca","55e680efde6fef23009480db","55e6829485a9741900314e99","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","589b8e1fdbb7cd190026732c","58b8ca5e3265d70f001788d4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-13T02:08:50.670Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"It is possible to import a list of existing push tokens into Carnival. This can be done with a structured [CSV](#section-csv-import) or [JSON](#section-json-import) file. \n\nBelow are requirements and guidelines for the format of data items in this file. If you want more general information, read [Migrating to Carnival](doc:migrating-to-carnival). \n\n## CSV Import\n\nIf the import file type is CSV then the first row should be the header record containing column (field) names. We only support custom attribute fields that are registered against the user. Default attributes such as locale, country, timezone, etc, will not be able to be updated via CSV. These default attributes are generated directly from the mobile app via the Carnival SDK. All CSV files sent to Carnival will have the same header row structure (i.e. no columns will be omitted).\n\nEach line in the import file should represent a user's device. Only scalar values are allowed (one value per attribute).\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`token`\",\n    \"0-1\": \"Yes\",\n    \"0-2\": \"The push token issued by Apple or Google\",\n    \"1-0\": \"`os_name`\",\n    \"1-1\": \"Yes\",\n    \"1-2\": \"The platform name. Use either `iOS` or `Android`.\",\n    \"2-0\": \"`user_id`\",\n    \"2-1\": \"No\",\n    \"2-2\": \"The ID of the user, if available. Can be any value.\",\n    \"3-0\": \"`custom.<DATA_TYPE>.<ATTRIBUTE_NAME>`\",\n    \"3-1\": \"No\",\n    \"3-2\": \"Custom user attributes you wish to import along with the token. Valid data type values are:\\n  * `integer`\\n  * `float`\\n  * `string`\\n  * `date`\\n  * `boolean`\\n\\nFor example, if you store the customer's life time value as an integer, your field name could be named `custom.integer.life_time_value`.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Duplicate tokens will be ignored during the import. If you have multiple User IDs belonging to the same tokens, only the first valid entry will be imported.\"\n}\n[/block]\n### Data items\n\n  * The number of items in each row should match the number of columns defined in the header row.\n  * All columns should be separated by a `,` character.\n  * Strings which include a `\"` character, should have the character escaped with `\"\"` (double quotations)\n  * If you do not want to set an attribute for a device, pass through an empty string between the commas using `,,`.\n\n## JSON Import\nYour JSON file should be an array of device objects. Your file should follow this structure:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"token\\\": \\\"device token\\\",\\n    \\\"os_name\\\": \\\"\\\",\\n\\n    // Optional\\n    \\\"custom\\\": {\\n      \\\"attribute_name_1\\\": {\\n        \\\"value\\\": \\\"attribute value\\\",\\n        \\\"type\\\": \\\"string\\\"\\n      },\\n      \\\"attribute_name_2\\\": {\\n        \\\"value\\\": \\\"attribute value\\\",\\n        \\\"type\\\": \\\"string\\\"\\n      }\\n    },\\n    \\\"user_id\\\": \\\"\\\" // Optional\\n  }\\n]\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Type\",\n    \"0-0\": \"`token`\",\n    \"0-1\": \"Yes\",\n    \"0-2\": \"`string`\",\n    \"1-0\": \"`os_name`\",\n    \"1-1\": \"Yes\",\n    \"1-2\": \"`string`\",\n    \"2-0\": \"`user_id`\",\n    \"2-1\": \"No\",\n    \"2-2\": \"`string`\",\n    \"0-3\": \"The push token issued by Apple or Google\",\n    \"1-3\": \"The platform name. Use either `iOS` or `Android`.\",\n    \"2-3\": \"The ID of the user, if available. Can be any string value.\",\n    \"h-3\": \"Description\",\n    \"3-0\": \"`custom`\",\n    \"3-1\": \"No\",\n    \"3-2\": \"`object`\",\n    \"3-3\": \"Dictionary where they the key is a `string` representing the attribute name, and the value is an `object`\",\n    \"4-0\": \"`custom.<attribute_name>.type`\",\n    \"4-1\": \"Yes (only if `custom` is present)\",\n    \"4-2\": \"`string`\",\n    \"4-3\": \"The data type for this attribute. Valid data type values are:\\n  * `integer`\\n  * `float`\\n  * `string`\\n  * `date`\\n  * `boolean`\",\n    \"5-0\": \"`custom.<attribute_name>.value`\",\n    \"5-1\": \"Yes (only if `custom` is present)\",\n    \"5-2\": \"As defined in `custom.<attribute_name>.type`\",\n    \"5-3\": \"The attribute's value. If the attribute type is `date`, use an ISO 8601 representation.\"\n  },\n  \"cols\": 4,\n  \"rows\": 6\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Duplicate tokens will be ignored during the import. If you have multiple User IDs belonging to the same tokens, only the first valid entry will be imported.\"\n}\n[/block]\n## Data types\nCarnival will make a best effort to parse the value into the specified data format. Only scalar values are allowed for custom attributes (one value per attribute).\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Data type\",\n    \"h-1\": \"Ranges/valid values\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"`integer`\",\n    \"h-3\": \"Notes\",\n    \"0-1\": \"`-2,147,483,647` to `2,147,483,647`\",\n    \"0-2\": \"`12`, `24`, `25`\",\n    \"0-3\": \"Floating point numbers are accepted but they will be truncated to an `integer`. If you wish to keep the decimal part, use `float` instead.\",\n    \"1-0\": \"`float`\",\n    \"1-2\": \"`12.343`, `123.33`\",\n    \"2-0\": \"`string`\",\n    \"2-2\": \"`Cody`, `gold`, `A string with a , comma`\",\n    \"2-1\": \"UTF-8 character encoding\",\n    \"2-3\": \"In a CSV, wrap `,` in quotation marks, and `\\\"` in double quotation marks.\",\n    \"3-0\": \"`date`\",\n    \"3-1\": \"ISO 8601, e.g. `YYYY-MM-ddTHH:mm:ssZ`\",\n    \"3-2\": \"`2017-02-06T18:25:32+0300`\",\n    \"4-0\": \"`boolean`\",\n    \"4-1\": \"`true` or `false`\"\n  },\n  \"cols\": 4,\n  \"rows\": 5\n}\n[/block]\n## The import process\nThe import process is structured to ensure Carnival only import quality data.\n\n1. We will check the import file to verify it has the correct format required to proceed. If the data is valid, we will import it into a test app.\n1. You will need to verify the data and notify Carnival that the import can proceed. If you need to add additional data, you will need to update the import file. We will then proceed with a new upload to a new test app.\n1. Once you're satisfied with the data, we will then import the data into your production app.\n\n## Next Steps\n\nIt is important to remember that as the app update is installed, and the user starts to use the app, the [anonymous user](http://docs.carnival.io/v1.0/docs/migrating-to-carnival#section-what-can-you-do-with-these-anonymous-installs-within-carnival-) will be replaced by the real user. \n\n**This means that their attributes will be removed.** To address this, make sure you set the current values of the [user attributes](http://docs.carnival.io/v1.0/docs/collecting-user-data#user-attributes) on the first launch of the updated app.","excerpt":"","slug":"csv-format-for-push-token-import-into-carnival","type":"basic","title":"File Format for Token Import"}

File Format for Token Import


It is possible to import a list of existing push tokens into Carnival. This can be done with a structured [CSV](#section-csv-import) or [JSON](#section-json-import) file. Below are requirements and guidelines for the format of data items in this file. If you want more general information, read [Migrating to Carnival](doc:migrating-to-carnival). ## CSV Import If the import file type is CSV then the first row should be the header record containing column (field) names. We only support custom attribute fields that are registered against the user. Default attributes such as locale, country, timezone, etc, will not be able to be updated via CSV. These default attributes are generated directly from the mobile app via the Carnival SDK. All CSV files sent to Carnival will have the same header row structure (i.e. no columns will be omitted). Each line in the import file should represent a user's device. Only scalar values are allowed (one value per attribute). [block:parameters] { "data": { "h-0": "Field name", "h-1": "Required", "h-2": "Description", "0-0": "`token`", "0-1": "Yes", "0-2": "The push token issued by Apple or Google", "1-0": "`os_name`", "1-1": "Yes", "1-2": "The platform name. Use either `iOS` or `Android`.", "2-0": "`user_id`", "2-1": "No", "2-2": "The ID of the user, if available. Can be any value.", "3-0": "`custom.<DATA_TYPE>.<ATTRIBUTE_NAME>`", "3-1": "No", "3-2": "Custom user attributes you wish to import along with the token. Valid data type values are:\n * `integer`\n * `float`\n * `string`\n * `date`\n * `boolean`\n\nFor example, if you store the customer's life time value as an integer, your field name could be named `custom.integer.life_time_value`." }, "cols": 3, "rows": 4 } [/block] [block:callout] { "type": "info", "body": "Duplicate tokens will be ignored during the import. If you have multiple User IDs belonging to the same tokens, only the first valid entry will be imported." } [/block] ### Data items * The number of items in each row should match the number of columns defined in the header row. * All columns should be separated by a `,` character. * Strings which include a `"` character, should have the character escaped with `""` (double quotations) * If you do not want to set an attribute for a device, pass through an empty string between the commas using `,,`. ## JSON Import Your JSON file should be an array of device objects. Your file should follow this structure: [block:code] { "codes": [ { "code": "[\n {\n \"token\": \"device token\",\n \"os_name\": \"\",\n\n // Optional\n \"custom\": {\n \"attribute_name_1\": {\n \"value\": \"attribute value\",\n \"type\": \"string\"\n },\n \"attribute_name_2\": {\n \"value\": \"attribute value\",\n \"type\": \"string\"\n }\n },\n \"user_id\": \"\" // Optional\n }\n]\n", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field name", "h-1": "Required", "h-2": "Type", "0-0": "`token`", "0-1": "Yes", "0-2": "`string`", "1-0": "`os_name`", "1-1": "Yes", "1-2": "`string`", "2-0": "`user_id`", "2-1": "No", "2-2": "`string`", "0-3": "The push token issued by Apple or Google", "1-3": "The platform name. Use either `iOS` or `Android`.", "2-3": "The ID of the user, if available. Can be any string value.", "h-3": "Description", "3-0": "`custom`", "3-1": "No", "3-2": "`object`", "3-3": "Dictionary where they the key is a `string` representing the attribute name, and the value is an `object`", "4-0": "`custom.<attribute_name>.type`", "4-1": "Yes (only if `custom` is present)", "4-2": "`string`", "4-3": "The data type for this attribute. Valid data type values are:\n * `integer`\n * `float`\n * `string`\n * `date`\n * `boolean`", "5-0": "`custom.<attribute_name>.value`", "5-1": "Yes (only if `custom` is present)", "5-2": "As defined in `custom.<attribute_name>.type`", "5-3": "The attribute's value. If the attribute type is `date`, use an ISO 8601 representation." }, "cols": 4, "rows": 6 } [/block] [block:callout] { "type": "info", "body": "Duplicate tokens will be ignored during the import. If you have multiple User IDs belonging to the same tokens, only the first valid entry will be imported." } [/block] ## Data types Carnival will make a best effort to parse the value into the specified data format. Only scalar values are allowed for custom attributes (one value per attribute). [block:parameters] { "data": { "h-0": "Data type", "h-1": "Ranges/valid values", "h-2": "Example", "0-0": "`integer`", "h-3": "Notes", "0-1": "`-2,147,483,647` to `2,147,483,647`", "0-2": "`12`, `24`, `25`", "0-3": "Floating point numbers are accepted but they will be truncated to an `integer`. If you wish to keep the decimal part, use `float` instead.", "1-0": "`float`", "1-2": "`12.343`, `123.33`", "2-0": "`string`", "2-2": "`Cody`, `gold`, `A string with a , comma`", "2-1": "UTF-8 character encoding", "2-3": "In a CSV, wrap `,` in quotation marks, and `\"` in double quotation marks.", "3-0": "`date`", "3-1": "ISO 8601, e.g. `YYYY-MM-ddTHH:mm:ssZ`", "3-2": "`2017-02-06T18:25:32+0300`", "4-0": "`boolean`", "4-1": "`true` or `false`" }, "cols": 4, "rows": 5 } [/block] ## The import process The import process is structured to ensure Carnival only import quality data. 1. We will check the import file to verify it has the correct format required to proceed. If the data is valid, we will import it into a test app. 1. You will need to verify the data and notify Carnival that the import can proceed. If you need to add additional data, you will need to update the import file. We will then proceed with a new upload to a new test app. 1. Once you're satisfied with the data, we will then import the data into your production app. ## Next Steps It is important to remember that as the app update is installed, and the user starts to use the app, the [anonymous user](http://docs.carnival.io/v1.0/docs/migrating-to-carnival#section-what-can-you-do-with-these-anonymous-installs-within-carnival-) will be replaced by the real user. **This means that their attributes will be removed.** To address this, make sure you set the current values of the [user attributes](http://docs.carnival.io/v1.0/docs/collecting-user-data#user-attributes) on the first launch of the updated app.