-
Notifications
You must be signed in to change notification settings - Fork 5
Interfaces
Chris Horn edited this page Jun 28, 2014
·
10 revisions
####Mobile App####
There are two flows for how data moves between the mobile app and the website.
- Question(s) are sent via the website to mobile app users to inquire about a specific topic (such as 'do you use public transportation to get to work each day?'). App users are presented with the question(s) and can choose to respond to them via radio button, and/or including a media response (text, audio, video, picture) to the question.
- Mobile app users send feedback about a topic to the website without prompt. Media (text, audio, video, picture) is sent to the website without any prompt.
Flow
- The app will poll for a question
- If there is a question, it will show a notification so the user can answer it
- The user will respond to the question and include media
- The app will upload all media types and get ID's for them from the HTTP POST response json
- The app will upload the response payload with the media id's within it
-- or --
- The user will generate a post to send to the website. <see 4 and 5 above>
Interfaces
The mobile app will poll (once a day or less) the website for available questions to present to the user. Here is what the response from that polling will look like:
{
"question_available": true,
"question_id": "0123456789ABCDEF",
"question_utc_date_time": "2014-05-13 11:43:78",
"geofence": {
"topleft": {
"lat": 43.205825,
"lng": -77.676785
},
"bottomright": {
"lat": 43.112161,
"lng": -77.512677
},
},
"question_texts": [
{
"question_language_id": 1,
"question_text": "Do you use public transportation to get to work each day?",
"answer_values": [
{
"answer_text": "Yes",
"answer_value": "Yes",
"answer_meta": {}
},
{
"answer_text": "No",
"answer_value": "No",
"answer_meta": {}
},
{
"answer_text": "Not every day, but sometimes",
"answer_value": "Not every day",
"answer_meta": {}
}
]
},
{
"question_language_id": 2,
"question_text": "¿Utiliza el transporte público para ir a trabajar todos los días?",
"answer_values": [
{
"answer_text": "Sí",
"answer_value": "Sí",
"answer_meta": {}
},
{
"answer_text": "No",
"answer_value": "No",
"answer_meta": {}
},
{
"answer_text": "No todos los días, pero a veces.",
"answer_value": "No todos los días.",
"answer_meta": {}
}
]
}
],
"question_type": 0,
"allowed_media": [
"text",
"video",
"audio",
"image"
],
}
Breakdown of fields:
question_available
type: boolean
valid values:
description: field to test to see if there is a question that is available for display
question_id
type: text
description: unique id of the question.
question_utc_date_time
type: UTC time
format: YYYY-MM-DD HH:MM:SS
description: date/time of the posted question.
geofence
type: dictionary
description: optional geo fence to apply for the question. If the app is not within the fence
then the question will not be shown.
question_texts
type: array
description: array of dictionaries holding question text.
question_language_id
type: int
description: the id of the language that the question is in.
question_type
type: int
description: what type of question is it? multiple choice, radio, free-field text, etc.
answer_values
type: array
description: an array of possible answer values. in the event of free-field text, this
is empty.
answer_text
type: text
description: the display text for the possible answer
answer_value
type: text
description: a unique value for the question answer. this may be different than the
answer_text field
answer_meta
type: dictionary
description: can hold anything. placeholder for future work.
allowed_media
type: array
description: an array of strings of valid media types for this question. this really should
almost always all four types: text, video, audio, image
Once the mobile app has received this information, it can send a response back to the website. Note that the interface from the mobile app to the website is identical for both flow 1 and flow 2. Since three of the four media types that can be posted are not text, but binary blobs, they will have their own API. Media files will be pushed to the web with a simple HTTP POST.
Here are the fields that need to exist for the HTTP POST (ref here):
Unique App ID
name: unique_app_id
type: text
Media Type
name: media_type
type: text
Media Payload
name: media_payload
type: file
Example HTML:
<form action="media_upload.json">
<input type="text" name="unique_app_id">
<input type="text" name="media_type">
<input type="file" name="media_payload">
<input type="submit" value="submit">
</form>
Here is what that upload API response looks like:
{
"success": true,
"media_type": "video",
"media_id": "0011223344556677",
"upload_utc_date_time": "2014-05-13 18:22:07",
}
Breakdown of fields:
success
type: boolean
description: true/false value of a successful upload.
media_type
type: text
description: type of the media that was uploaded (same as HTTP POST field)
media_id
type: text
description: unique id for the media that was uploaded. this is used within the user
response/post json document in the media_id field.
upload_utc_date_time
type: UTC time
format: YYYY-MM-DD HH:MM:SS
description: date/time of the posted question.
Here is what a users response looks like to a question:
{
"unique_app_id": "0102030405060708",
"source": 0,
"location": {
"lat": 43.1656,
"lng": -77.6114
}
"response_to_question": true,
"question_id": "0123456789ABCDEF",
"question_answer": {
"answer_text": "Yes",
"answer_value": "Yes",
"answer_meta": {}
}
"post_utc_date_time": "2014-05-13 18:22:07",
"post_language_code": 1,
"media": {
"text": {
"text_value": "It's cheap, and it's just a 5 minute ride ... why wouldn't I!?"
},
"video": {
"video_id": ""
},
"audio": {
"audio_id": ""
},
"image": {
"image_id": "98765F4E3D2C1B0A"
}
}
}
If this was not a response to a question, it may look like this:
{
"unique_app_id": "0102030405060708",
"source": 1,
"location": {
"lat": 0,
"lng": 0
}
"response_to_question": false,
"question_id": "",
"question_answer": {
}
"post_utc_date_time": "2014-05-13 18:22:07",
"post_language_code": 1,
"media": {
"text": {
"text_value": "Abandoned, decrepit building at 1234 Rose St."
},
"video": {
"media_id": ""
},
"audio": {
"media_id": ""
},
"image": {
"media_id": "AABBCCDDEEFF0123"
}
}
}
unique_app_id
type: string
description: this is the unique id of the device the app is installed on. In the event
that this is a post from the website, a 5 letter code will be generated
source
type: int
description: the source of the post (either from the mobile app or the website). mobile app
is a value of 0 and the website is a value of 1.
location
type: dictionary
description: dictionary holding information about the location of the post.
lat
type: double
description: latitude value of the app when posting. if from the website, a value of zero
should be used.
lng
type: double
description: longitude value of the app when posting. if from the website, a value of zero
should be used.
response_to_question
question_id
question_answer
answer_text
type: text
description: the display text for the possible answer. this is the same values as that
existed within the question json dictionary from the website.
answer_value
type: text
description: a unique value for the question answer. this may be different than the
answer_text field. this is the same values as that existed within the question
json dictionary from the website.
answer_meta
type: dictionary
description: can hold anything. placeholder for future work. this is the same values as that
existed within the question json dictionary from the website.
post_utc_date_time
type: UTC time
format: YYYY-MM-DD HH:MM:SS
description: date/time of the posted response.
question_language_id
type: int
description: the id of the language that the question is in
media
type: dictionary
description: a dictionary of dictionaries that hold the values or id's of the media that was
included in the response/post.
text
type: dictionary
description: holds the text of the text media.
text_value
type: text
description: the text that was included with the response/post. this field will always be
here, however may be empty.
video
type: dictionary
description: holds the id of the video media.
audio
type: dictionary
description: holds the id of the audio media.
image
type: dictionary
description: holds the id of the image media.
media_id
type: text
description: holds the id of of the uploaded media. this id comes from the HTTP POST json
response.