docs updated to incude fields I need for my app. Details may change a…

…s iOS version implemented, but fields supported likely wont.
binzailani3136 · Dec 8, 2016 · 76dcf1f · 76dcf1f
1 parent 214867e
commit 76dcf1f
Showing 1 changed file with 65 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -34,16 +34,34 @@ The following contact fields are supported on iOS and Android. Where a field lab
 | givenName  | String     | R/W  | R/W     | Given name or "first name"
 | middleName | String     | R/W  | R/W     | Middle name or names
 | nickName   | String     | *    | R/W     | Contact's nickname
+| phoneticName | Object   | *    | * [notes](#phoneticName) | see [phoneticName](#phoneticName)
 | company    | String     | *    | R/W     | Where the Contact works
-| jobTitle   | String     | *    | R/W     | Contact's job title
+| jobTitle   | String     | R/W  | R/W     | Contact's job title
 | phoneNumbers | Array    | R/W  | R/W     | see [phoneNumbers](#phoneNumbers)
 | emailAddresses | Array  | R/W  | R/W     | see [emailAddresses](#emailAddresses)
 | websites   | Array      | *    | R/W     | see [websites](#websites)
-| postalAddresses| Array  | *    | *       | see [postalAddresses](#postalAddresses)
+| postalAddresses| Array  | *    | R/W     | see [postalAddresses](#postalAddresses)
 | note       | String     | *    | R/W     | Note about contact. Appears in "Notes" on native Contact Manager
-| birthday   | String     | *    | *     | The contact's birthday, with or without year, as a String
+| birthday   | Object     | *    | *     | The contact's birthday, with or without year, as ```{ year: int, month: int, day: int }```
+| socialServices | Array  | *    | *       | see [socialServices](#socialServices)
 | thumbnailPath | String  | R/*  | R/W     | A 'file://' URL pointing to the contact's thumbnail image on the native device filesystem. See [Notes on adding and updating thumbnailPath](#notes-on-adding-and-updatring-thumbnailPath)
-\* *Support planned*
+\* *Support planned but implementation pending - comments and suggestions welcome*
+
+#### phoneticName
+
+** IMPLEMENTATION PENDING **
+
+An Object containing phonetic representations of the contacts names.
+
+Notes:
+
+iOS supports separate phonetic name fields, while Android only supports a single combined phonetic name field. To make phoneticName bidirectional, no whitespace should appear in either individual field. If a phonetic name field passed to addContact() or writeContact() contains spaces, they will be replaced with hyphens (-).  For example: "CAR el" "YUH ng" will become "CAR-el" "YUH-ng". On iOS the hyphenated version of each name will be added, while on Android they will be concatenated into the single field "CAR-el YUH-ng". When fetched with getAll(), Android will use the space (%20) as a delimiter.
+
+| Key Name   | Value Type | Description |
+|------------|------------|-------------|
+| family     | String     | Phonetic representation of contact's family name without spaces (use "-" instead) |
+| given      | String     | Phonetic representation of contact's given name (use "-" instead) |
+| easternOrder | boolean    | Default = *false* If true, Android will concatenate with the family name first and the given name second. *A phonetic name written in Eastern order is not currently guaranteed to be retrieved in correct order on Android.*
 
 #### phoneNumbers
 
@@ -53,7 +71,7 @@ An array of Objects containing phone numbers with the following key names:
 |------------|------------|-------------|
 | label      | String     | One of: *home, work, mobile, fax, other*. An unrecognzied label will be added as 'other'|
 | number     | String     | A String containing the phone number associated with *label*
-| primary    | boolean    | Default = *false* *(WIP) Indicates this number is the Contact's primary number. If more than one phone number is provided to addContact() the number added as the primary contact number is undefined*
+| primary    | boolean    | Default = *false* *(WIP) Indicates this number is the Contact's primary number. If more than one phone number is provided to addContact() in the array, and none or more than one have primary set to *true*, the number added as the primary contact number is undefined*
 
 
 #### emailAddresses
@@ -64,7 +82,7 @@ An array of Objects containing email addresses with the following key names:
 |------------|------------|-------------|
 | label      | String     | One of: *home, work, mobile, other*. An unrecognzied label will be added as 'other'|
 | email      | String     | A String containing the email address associated with *label*
-| primary    | boolean    | Default = *false* *(WIP) Indicates this email address is the Contact's primary email address. If more than one email address is provided to addContact() the address added as the primary contact email address is undefined*
+| primary    | boolean    | Default = *false* *(WIP) Indicates this email address is the Contact's primary email address. If more than one email address is provided to addContact() in the array, and none or more than one have primary set to *true*, the address added as the primary contact email address is undefined*
 
 
 #### websites
@@ -78,7 +96,33 @@ An array of Objects containing phone numbers with the following key names:
 
 #### postalAddresses
 
-**WIP**
+An array of Objects containing postal (physical) addresses with the following key names:
+
+| Key Name   | Value Type | Description |
+|------------|------------|-------------|
+| label      | String     | One of: *home, work, other*. An unrecognzied label will be added as 'other'|
+| street     | String     | The complete street address ("123 N. Main Street Suite 500") associated with *label*
+| city       | String     | The city in which the address resides.
+| region     | String     | A location designation between *city* and *country*, if customary or necessary. For addresses in the USA this would be the "state", in Canada the "province", etc. *Platform note: Maps to "REGION" on Android and "STATE" on iOS.*
+| country    | String     | The *ISO 3166-1 ALPHA-2* country code. (Multilingual JSON files can be found at https://github.com/umpirsky/country-list)
+| postcode   | String     | The postal code (zip code) for this address.
+| primary    | boolean    | Default = *false* *(WIP) Indicates this postal address is the Contact's primary postal address. If more than one postal address is provided to addContact() in the array, and none or more than one have primary set to *true*, the address added as the primary postal address is undefined*
+
+#### socialServices
+
+** IMPLEMENTATION PENDING **
+
+An array of Objects containing social media accounts for the contact with the following key names. All keys except "serviceId" are optional.
+
+Android implementation notes: As of API 25, the native contact manager only supports IM services, not social media services.
+
+| Key Name   | Value Type | Description |
+|------------|------------|-------------|
+| serviceId  | String     | A label indicating the social media service. iOS currently supports: "facebook", "flickr", linkedin", "myspace", sinaweibo", tencentweibo", "twitter", "yelp", and "gamecenter", and "custom".
+| url | String | A URL associted with the social profile
+| uid | String | The user ID for this contact on this service
+| name | String | The name of this user on this service
+
 
 #### Notes on Adding and Updating thumbnailPath
 
@@ -104,7 +148,10 @@ When calling updateContact():
   givenName: "Carl",
   middleName: "C.",
   nickName: "Carl-o",
-
+  phoenticName: {
+    given: "CAR-el",
+    family: "YUH-ng"
+  }
   company: "Foomatics, Inc.",
   jobTitle: "Developer",
 
@@ -129,16 +176,20 @@ When calling updateContact():
 
   postalAddresses: [{
     label: "work",
-    unstructuredAddress: "123 N. Main Street, Anytown, NNN 12345-A234, Foolandia",
     street: "123 N Main Street"
-    city: "Anytown",
-    postCode: "12345-A234",
-    region: "NNN",
-    country: "Foolandia",
+    city: "Chicago",
+    region: "IL", //Illinois in USA
+    postcode: "12345-A234",
+    country: "US",
   }],
 
   note: "This is a note",
-  birthday: "Jun 8",
+
+  birthday: {
+      month: 6,
+      day: 12,
+  },
+
   thumbnailPath: "file:///device/path/to/image.jpg",
 }
 ```