Interfaces

Interfaces

####Mobile App####

There are two flows for how data moves between the mobile app and the website.

1. 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.
2. 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.

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",
    "question_texts": [
        {
            "question_language_id": 1,
            "question_text": "Do you use public transportation to get to work each day?"
        },
        {
            "question_language_id": 2,
            "question_text": "¿Utiliza el transporte público para ir a trabajar todos los días?"
        }
    ],
    "question_type": 0,
    "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": {}
        },
    ],
    "allowed_media": [
        "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 Payload
    name: media_payload
    type: file

Example HTML:

<form action="media_upload.json">
    <input type="text" name="unique_app_id">
    <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",
}

Here is what a users response looks like to a question:

{
    "unique_app_id": "0102030405060708",
    "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",
    "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"
        }
    }
}