{"_id":"575e15b28adab20e00b5fa59","project":"55e67aaa9cc7c62b00c4a1ea","parentDoc":null,"user":"55d29988486de50d00327118","__v":9,"category":{"_id":"55e67aac9cc7c62b00c4a1ee","version":"55e67aab9cc7c62b00c4a1ed","__v":3,"pages":["55e67aae9cc7c62b00c4a1f0","55e67bfd9cc7c62b00c4a1f5","55ecd59b54a67b1700edcf3c"],"project":"55e67aaa9cc7c62b00c4a1ea","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-02T04:27:24.277Z","from_sync":false,"order":0,"slug":"getting-started","title":"Getting started"},"version":{"_id":"55e67aab9cc7c62b00c4a1ed","project":"55e67aaa9cc7c62b00c4a1ea","__v":10,"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":"If you are migrating from another push provider (or from your existing homegrown solution), you can import a list of existing push tokens into Carnival. This can allow you to send push notifications to these devices and temporarily import other device properties (such as User IDs and attributes) so you can target these devices until they upgrade to Carnival.\n\nThis is a managed process and it is handled by Sailthru. To get started, you will need to provide a file in the format and with the requirements highlighted in this page. If you want more general information, read [Migrating to Carnival](doc:migrating-to-carnival). \n\n## File Format\n\nTokens must be passed as a CSV list (one token per line). The first row is a header record containing column (field) names. Only the alphanumeric part of the token must be passed; extra characters (such as `:`, `-`, `_` token separators) must be stripped out of the token value. For each token you must also specify the target platform.\n\nWe only support custom attribute fields that are registered against the user. For consistency purposes, attributes such as locale, country, timezone, etc, cannot be uploaded, as these default attributes are generated directly from the mobile app via the Carnival SDK.\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 APNS or FCM. Only alphanumerical values (`[a-zA-Z0-9]`) are allowed.\",\n    \"1-0\": \"`os_name`\",\n    \"1-1\": \"Yes\",\n    \"1-2\": \"The platform name. Use either `iOS` or `Android` (case sensitive).\",\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## 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.\n2. 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.\n3. 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


If you are migrating from another push provider (or from your existing homegrown solution), you can import a list of existing push tokens into Carnival. This can allow you to send push notifications to these devices and temporarily import other device properties (such as User IDs and attributes) so you can target these devices until they upgrade to Carnival. This is a managed process and it is handled by Sailthru. To get started, you will need to provide a file in the format and with the requirements highlighted in this page. If you want more general information, read [Migrating to Carnival](doc:migrating-to-carnival). ## File Format Tokens must be passed as a CSV list (one token per line). The first row is a header record containing column (field) names. Only the alphanumeric part of the token must be passed; extra characters (such as `:`, `-`, `_` token separators) must be stripped out of the token value. For each token you must also specify the target platform. We only support custom attribute fields that are registered against the user. For consistency purposes, attributes such as locale, country, timezone, etc, cannot be uploaded, as these default attributes are generated directly from the mobile app via the Carnival SDK. 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 APNS or FCM. Only alphanumerical values (`[a-zA-Z0-9]`) are allowed.", "1-0": "`os_name`", "1-1": "Yes", "1-2": "The platform name. Use either `iOS` or `Android` (case sensitive).", "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 `,,`. ## 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. 2. 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. 3. 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.