User Guide AJ De Las Alas, Tiffany Chan, Stephanie Tran, Viet Tran 1.0 Preface 1.1 Readme DELTA is an application that belongs to Julie Schweitzer s research group. After the application is opened, the study administrator or teacher needs to login respectively if they are already registered and in the system. If the user is a new study administrator and has the secret code, then he or she needs to register himself or herself. When the teacher logins successfully, he or she can start a session for a specific student for a number of trials that is set in the trial settings. When a study administrator is logged in, the administrator can manage teachers and students, edit trial settings, and start a session for a student by clicking the respective buttons on their menu screen. Before starting a trial, either the study administrator or teacher selects a student for that session and hands the tablet over to the student for the trials. The student will click on the Start Trial button, which leads him or her to the selection screen. He or she will decide which button he or she wants to click, either the Now or Wait button. If the student needs to stop in the middle of the selection, there is a pause and resume button the study administrator or the teacher can use. Once the student selects a button, he or she will either get to play the game first or has to wait first, depending on their choice for that one trial. 1.2 Audience The audience of DELTA is limited to the study administrators and teachers of Julie Schweitzer s research group and the preschool students that are participating in the research. 1.3 Vocabulary Study Administrator: anyone who is part of the research group, entitled to manage the application settings, to handle the test/trial data, and to administers the trials Teacher: anyone who is part of the research group and can only administers the trials Student: a preschool child who is receives the trials and has access to the game. 1.4 Navigation There is no navigational menu for the application because it runs in a sequential format. DELTA has incorporated a button to go back to the previous screens on the top left of the application. This back button will be hidden during the trial when the preschool student are using the tablet, so the student cannot press anything that might accidentally exit the trial or application. Before a trial starts, there is a dropdown on the top right of the application, which the study administrator or the teacher selects whether or not he or she wants to make the countdown timer for the wait time visible to students. After each trial is done, the application will go back to the Start Trial screen and continue like that until the specified number of trials has been completed. In addition, after each session is done for that one student, DELTA will return to the Start Session screen. From here, the study administrator or teacher can select from the dropdown menu start if he or she wants 1
to save the session and then quit or just quit without saving. Afterward, he or she can start another session with a different student. 2.0 Overview of the product Our product is an Android application called DELTA. It tests to see whether preschool students with impulsive behavior can increase their tolerance for delays and improve their selfcontrol as they progress through some number of trials and sessions. This application will be used by study administrators, teachers, and preschool students. The study administrators and teachers have access to the login screen, can run the session for each student, and administer the trials for each session. In addition to that, the study administrators have the ability to manage users and edit trial settings. The actual trial and game section of the application are designed for preschool students. DELTA also records data for the study administrators to analyze. 3.0 Installation or Distribution Our clients, Steve Riley and Julie Schweitzer, will receive BitBucket access to our source code of the application. The application can be installed on any compatible Android tablet by installing the corresponding APK file. The APK file can be generated in the following ways: Android Studio: o Build Generate Signed APK Press Next after enter all the fields Finish o Upon completion, a notification window will pop up saying Signed APK s generated successfully. o The generated APK file can be found by pressing Show in Explorer. Eclipse: o File Export Android Export Android Application Choose an existing keystore or create a new keystore Choose a destination directory for the generated apk file (where it will locate after the generation) Finish o Upon completion, the generated APK file can be found in the path indicated by you. 4.0 Functionality 4.1 Adding & Deleting Teachers / Students Both study administrators and teachers have the ability to add students when they start a session. However, only study administrators have the ability to manage (add or delete) both teachers and students from the administrator homepage. 2
(Manage Students screen is in the same format.) 4.2 Trial Settings The trial settings is used to control the number of trials per session and initial time for each trial. Study administrators also can select how many seconds to increment after however many trials they choose before updating to the new trial time. 3
' 4.3 Conduct a Session & Trial To start a session, the administrator or teacher selects the student id that is associated with the student that he or she will be doing the trial on. Then, he or she gives that student the tablet and allow them to choose between two choices of "Now" and "Wait." Next, the student gets to play the game or encounters the wait time screen first, depending on his or her selection. 4
5
4.4 Game The game is a similar to an infinite runner game. It displays a cat running across a field of grass, chasing and grabbing yarn balls. The user simply taps the screen for the cat to jump over potholes and to collect the yarn balls that are spawned. If the user falls into the pothole, the game will reset and the student gets to play until the time runs out. 6
5.0 Troubleshooting If anything goes wrong with the application such as a freeze in the middle of a session, the study administrator or teacher should restart the application and redo the session. 6.0 Frequently Asked Questions Q: How will the data be secured from the trials? A: Each student involved in the trial is assigned an ID on a document. The study administrator or teacher, who adds the student to the application, will be using the student's ID rather than the student's name. So, any stolen credentials will not be of any use without the document since the application will not have any student s name on it. The data received from the trials will be directly uploaded to Box at the study administrators' will. The only security precaution that we took was hashing the username and password of the study administrators when uploading this information to Box in order to use it across platforms. Q: How will the administrators upload the data that is locally stored on the device to Box if there is no WIFI available in the area? A: There is nothing that can be done when there is no WIFI connection. The administrators have to wait until WIFI is available to be able to click on the button that uploads the data automatically to Box. 7.0 Contact Information We are Team Phoenix, a team of UC Davis students. We can be contacted by email: AJ De Las Alas: ajdelasalas@ucdavis.edu Tiffany Chan: tikchan@ucdavis.edu Stephanie Tran: iistran@ucdavis.edu Viet Tran: vietran@ucdavis.edu 7
8.0 Index Adding & Deleting Teachers / Students: 2, 3 APK: 2 BitBucket: 2 Box: 7 Contact Information: 7 FAQ: 7 Game: 6, 7 How to use: 1 Navigation: 1, 2 Session: 4-6 Trial: 4-6 Trial Settings: 3, 4 Troubleshooting: 7 9.0 Appendix This section includes the Design Document and the Testing Document. 9.1 Design Document DELTA Design Document AJ De Las Alas, Tiffany Chan, Stephanie Tran, Viet Tran Table of Contents 1. Technology Background 2. Design Goals 2.1 Correctness 2.2 Ease of Use 2.3 Reliability & Usability 2.4 Reusability 2.5 Maintainability 3. Architectural Choices and Corresponding Pros and Cons 4. Selected Architecture 5. Android Application 5.1 Overview 5.2 Login 5.3 Manage Teachers / Students 5.4 Start Session 5.5 Trial Settings 6. Human Interface Design 6.1 General Overview of Interface Design 6.2 Front Page of Application 6.3 Login 6.4 Administrator Registration 8
6.5 Administrator Homepage 6.6 Manage Teachers 6.7 Trial Settings 6.8 Select Student for Session 6.9 Trial Selection 7. Implementation Notes 1. Technology Background We choose to use Android Studio as the IDE for our Android application development because it is the official IDE and developer tool for Android smartphones and tablets. Our application, DELTA, has a user interface in which administrators, teachers, and students use but each group of people have access to different features and settings and an infinite runner game. The goal of this application is to see whether a group of preschool children with high rates of impulsivity can obtain self-control and achieve delayed gratification. Android Studio provides code templates to help build common application features and it provides a rich layout editor with support for drag and drop theme editing. In addition, this software is an all-in-one developmental tool because no separate Android SDK package needs to be downloaded or maintained. Lastly, it features a new, nicer, and improved interface design in which one can view the interface and its related components. With this feature, we can edit and preview our Android layouts across multiple screen sizes, languages, and API versions. 2. Design Goals 2.1 Correctness Our primary goal is to create an efficient, non-faulty, and working application. In order to accomplish that, the application must satisfies the requirements of the project. Debugging will be needed to identify, reduce, and fix the amount of bugs in the source code. Verification can be used to check whether the written code works with all its features. Two examples of verification techniques are unit testing and regression testing, which are going to be used to reveal errors of functionalities or bugs in the code. 2.2 Flexibility and Ease to Use Flexibility, the ability the change, is necessary because requirements may change during or after the project. Examples of such changes might be adding more to what is currently present in the application, adding new kinds of functionalities, and changing the implemented functionalities. Design decisions to promote flexibility are keeping the code simple, refrain from repeating code, and encapsulation. 2.3 Reliability & Usability The application must be reliable because data must be collected and recorded. Therefore, in the case of a system crash or errors, the data has to be still available and present for the administrators to access for research purposes. This data includes response, response time, trial 9
time, and delay time of each participant. Reliability could be achieved by testing. Another aspect is usability in which users find the application easy to use and navigate. Good documentation and an intuitive, clear UI with a standard layout are methods to provide usability, allowing beginners to use the application with ease. 2.4 Reusability A software design goal of our application is reusability so other programmers can reuse source code. To promote the reuse of source code, we can use modularity and write good methods with documentation and meaningful variable names. 2.5 Maintainability Maintainability is a combination of flexibility and bug fixes. DELTA needs to be a maintainable software because it can undergo changes to satisfy new or changing requirements such as enhancing or updating existing and correcting code errors. Achieving maintainability depends on various tools and techniques. Some of these tools and techniques are proper test cases, good documentation, modular design, debugging, and object-oriented design. 3. Architectural Choices and Corresponding Pros and Cons The two architectural choices that we were debating between are the MVC (Model-View- Controller) pattern and Pipes and Filters style. The pros to MVC are that it supports multiple views of Model and separates Model from View, which allows multiple representations to be developed. This separation between Model and View presents the privilege of making testing relatively easy. Another good aspect of this architectural pattern is it accommodates change because View can be changed without any impact on Model or Controller. However, the cons are the increased complexity since MVC introduces extra levels of indirection and possibly flood View with constant change and update events. On the other hand, there is the Pipes and Filter style. The corresponding pros are the filters are reusable and can evolve separately and the individual filters are easy to test. In addition, this style also features naturally concurrent execution. Some cons to using Pipes and Filters architectural style are filters are monolithic, it is not compatible with interactive computing, and data uniformity may cause lowest common denominator. Another poor feature is that the communication pattern is restricted. 4. Selected Architecture Our selected architecture style is MVC (Model-View-Controller) because it is a pattern for implementing user interfaces. The Model in MVC notifies View and Controller of state updates (active) or state is polling (passive). View generates output representation when there is a notification of state changes or requests state from Model. The Controller sends commands to the Model to update the state and may command View of the representation change. 10
5. Android Application 5.1 Overview DELTA is an application that is used by administrators, teachers, and students. Administrators are able to login, manage teachers and students, run sessions with the students, and edit trial settings. Teachers are able to only run sessions with the students. The students are the participants, who are actively interacting with the trial and game part of the application. The following flow charts show how the major functionalities and features of the application flow and work together. 11
5.2 Login 5.3 Manage Teachers / Students 12
5.4 Start Session 13
5.5 Trial Settings 6. Human Interface Design 6.1 General Overview of Interface Design The sections below present images of a simple user interface but they do not include all aspects of the application. Changes will be made to the interface to make it more appealing and creative to the users. Despite the changes to design of our user interface, the layout will remain consistent through the application. 14
6.2 Front Page of Application 15
6.3 Login 16
6.4 Administrator Registration 17
6.5 Administrator Homepage 18
6.6 Manage Teachers 19
6.7 Trial Settings 20
6.8 Select Student for Session 21
6.9 Trial Selection 22
7. Implementation Notes We are using Android Studio to develop our application, so we will be using Java and the Android API. We are using each activity to represent each page of our app and by clicking the buttons in each activity will cause transition to another activity. Each activity has its own associated XML file which is responsible for its visual design and element layout. The app will start with a button that launch the user to a login page. There are two type of users that can login, teacher and administrator. Teachers have less authority than the administrator, they can only edit their password and start a trial for student. Administrators have, in addition to the mentioned features, the capability to manage teachers and students that are already in the system, edit the setting for the experiment session, and access the recorded data. Also, new administrators will be able to register themselves through login page. However, for security purposes, they will have to obtain a secret code from existing administrators in order to complete registration. The beginning page of the experiment consists of a big button of starting the trial; once the button is pressed, it will transit to the next page and start recording the response time. The next page contains two big buttons for the choices (delay or instant access). The choice will also be recorded. All recorded data are associated with a particular student that is selected by the teacher/ administrator prior to the beginning of the session, We are going to use an existing code for some infinite running game and modify it such that it will be suitable and addicting to pre-school child. All data will be stored to csv file and upload to Google Drive, using Google Drive API, and such file will only be accessible by administrators. 23
9.2 Testing Document Test Cases AJ De Las Alas, Tiffany Chan, Stephanie Tran, Viet Tran 1. User Type: Teacher, Administrator Goal: Logging in to use the application Initial Conditions: The user has to be already registered with an account. Test Script: a. User clicks on "Start App" button b. App loads the Login page c. User enters username and password and clicks on "Teacher Login" or "Administrator Login" button d. App checks if the correct username and password are entered. e. If incorrect username or password was entered, app prompts the user to reenter the following fields f. If correct, login is successful. App loads the corresponding homepage depending on user type. 2. User Type: New Administrator Goal: New administrator registering for an account Initial Conditions: Must have a confirmation code Test Script: a. User clicks on "Start App" button b. App loads the Login page c. User selects "Register New Administrator" button, fills in the fields: Username, Password, Repeat Password, and Confirmation Code, and clicks on "Register" button. d. If all fields are correct, the user will be logged in successfully and the app load the Administrator Homepage. e. If one of the fields are incorrect, the app prompts the user to reenter the following fields. Variations: a. The user can choose to cancel the registration by clicking on the "Cancel" button. 3. User type: Administrator Goal: Manage teachers/ students (add / delete) Initial Condition: User is already logged in as an admin Test Script: a. User selects Manage Teachers or Manage Students button from Administrator Homepage b. App loads the corresponding page c. User select Add Teacher button d. App loads input field and a Add button e. User enters username and password of new teacher and click Add button f. App checks database to ensure new username is unique and password is valid, once checked, app adds the new teacher to the system g. User can also select Delete Teacher button 24
h. App loads dropdown menu consists of list of teachers in the system and a Delete button i. User expands the dropdown menu and select a teacher, then clicks delete button j. App removes the selected teacher from the system k. User clicks the backward arrow on the top, left corner to return to the Administrator Homepage. 4. User type: Administrator Goal: Change the trial settings of the experiment Initial Condition: User is already logged in as an administrator Test Script: a. User selects Trial Setting button from Administrator Homepage b. App loads the Trial Setting page c. User uses the number pickers to select desired values for i. Total number of trials ii. Initial trial time iii. Increment interval iv. Increment trial time by how many trials d. User clicks "Save Changes" button to preserve changes and return back to the Administrator Homepage. e. Otherwise, user clicks "Cancel" button to discard any changes made and return back to the Administrator Homepage. 5. User Type: Teacher, Administrator Goal: Starting a session for a student Initial Conditions: The user has to be logged in. Test Script: a. User selects "Start Session" button b. App loads the Select Student for Session page c. User uses the dropdown menu to select the student for the session and then clicks the "Select" button. d. App loads Begin Trial page. Variations: a. If the user doesn't select a student, the app will prompt the user to select a student first. b. If the student isn't listed under the dropdown menu, the user selects the "Add Student" button, enter the student ID, and clicks the "Enter" button. The student is added and user can select the student from the dropdown menu. 6. User type: Student Goal: To perform the experiment Initial Condition: Administrator / Teacher started the experiment session for the selected student Test Script: a. App loads Start Trial Page b. User selects Start Trial button c. App loads the selection page and starts the time counter in the background 25
d. Administrator / Teacher can select Pause button when necessary. e. App pauses the time counter and set the Now and Wait button un-clickable f. Administrator / Teacher can then selects Resume button to resume trial. g. App resumes the time counter and set the Now and Wait button clickable h. User can selects Now button or "Wait" button i. If user selects "Now" button, then i. App stops the time counter and records the user s response and response time ii. App loads the game iii. User plays the game for a fixed amount of time (for instant time access) iv. After game is done, app loads the Start Trial Page v. App loads the selection page and starts the time counter in the background j. If user selects Wait button, then i. App stops the time counter and records the user s response and response time ii. App loads waiting page for a fixed amount of waiting time iii. App loads the game once the waiting time ends iv. User plays the game for a fixed amount of time (for waited trial) v. After game is done, app loads Start Trial Page & loop selection page k.session ends (see variations) l. App loads all recorded data to database m. App loads back to Start Session page and prepare a new session to start Variations: a. Session ends when user completes all the trials b. Session ends when user choose to exit the session before all the trials are completed 26