Compare Revisions

Firefox OS Simulator

Revision 438013:

Revision 438013 by Luca.greco on

Revision 439683:

Revision 439683 by Mykmelez1 on

Firefox OS Simulator
Firefox OS Simulator
"Tools","Apps","Firefox OS"
"Tools","Apps","Firefox OS"

Revision 438013
Revision 439683
nn14      <p>
15        Read <a href="#Simulator-verbose-logging" title="#Simulat
 >or-verbose-logging">how to enable verbose logging</a> and <a href
 >="#Simulator-latest-preview-build" title="#Simulator-latest-previ
 >ew-build">get the latest preview build</a> in the <a href="#Unsup
 >ported-APIs" title="#Unsupported-APIs">Getting help</a> section.
16      </p>
n33      The Dashboard is on the top-right, running inside a Firefoxn36      The Dashboard is on the top-right, running inside a Firefox
> tab. We've added one app, a packaged app called "Where am I?". A> tab. We've added one app, a packaged app called "Where am I?". A
>t the top-left the app is running in the Simulator. We've also co>t the top-left the app is running in the Simulator. We've also co
>nnected the debugging tools, which are in the window at the botto>nnected the debugging tools, which are in the panel at the bottom
>m. You can see that we've just hit a breakpoint in the app.>. You can see that the Console pane displays messages about the a
34    </p>
35    <p>37    </p>
38    <p>
36      <img alt="" src="      <img alt="" src="
>mulator-overview.png">>mulator-overview-4.0.png" style="width: 900px; height: 632px;">
n46        <a href="#Adding-updating-removing" title="#Adding-updatin49        <a href="#Adding-updating-removing" title="#Adding-updati
>ng-removing">how to add, remove, and update apps</a>>ng-removing">how to add, remove, and refresh apps</a>
nn61        <a href="#Simulator-receipts" title="#Simulator-receipts"
 >>how to get test receipts for a paid app</a>
62      </li>
63      <li>
64        <a href="#Push-to-device" title="#Push-to-device">how to 
 >push apps to a connected device</a>
65      </li>
66      <li>
nn70    <div class="geckoVersionNote">
61    <p>71      <p>
62      For a practical walkthrough that shows how to use the Simul72        For a practical walkthrough that shows how to use the Sim
>ator to debug a real web app, see the <a href="/en-US/docs/Tools/>ulator to debug a real web app, see the <a href="/en-US/docs/Tool
>Firefox_OS_Simulator/Simulator_Walkthrough" title="/en-US/docs/To>s/Firefox_OS_Simulator/Simulator_Walkthrough" title="/en-US/docs/
>ols/Firefox_OS_Simulator/Simulator_Walkthrough">Simulator Walkthr>Tools/Firefox_OS_Simulator/Simulator_Walkthrough">Simulator Walkt
>ough</a> page.>hrough</a> page.
63    </p>73      </p>
74    </div>
n88      The Dashboard is the tool you use to add your app to the Sin99      The Dashboard is the tool you use to add your app to the Si
>mulator and run it. Here's what it looks like:<br>>mulator and run it. Here's what it looks like: <img alt="" src="h
 >ttps://" style="
 >width: 1044px; height: 650px;">
89      <img alt="" src="    </p>
>shboard.png" style="width: 963px; height: 720px;"> 
90    </p>101    <p>
102      &nbsp;
103    </p>
91    <h2 id="Adding.2C_updating.2C_and_removing_apps">104    <h2 id="Adding.2C_removing.2C_and_refreshing_apps">
92      <a name="Adding-updating-removing" id="Adding-updating-remo105      <a name="Adding-updating-removing" id="Adding-updating-remo
>ving">Adding, updating, and removing apps</a>>ving">Adding, removing, and refreshing apps</a>
n112      <img alt="" src="      <img alt="" src="
>shboard-list-apps.png"><br>>shboard-list-apps-4.0.png" style="width: 1044px; height: 650px;">
n126      It also gives us three commands:n139      It also gives us four commands:
127    </p>
128    <ul>140    </p>
129      <li>"Remove": remove the app from the Simulator or the Dash141    <ul>
>board. You can undo this action as long as the Dashboard tab is o 
130      </li>142      <li>
131      <li>"Update": use this to update the app in the Simulator a143        <strong>"Refresh":</strong> use this to update and reload
>fter you have made changes to it. This also makes the Dashboard v> the app in the Simulator after you have made changes to it. This
>alidate the manifest again. If you make changes to your app they > also makes the Dashboard validate the manifest again. If you mak
>will not be reflected automatically in the installed app: you wil>e changes to your app they will not be reflected automatically in
>l need to click "Update", and restart the Simulator if it is runn> the installed app: you will need to refresh the app to apply the
>ing.> changes.
144      </li>
132      </li>145      <li>
133      <li>"Run": run the app in the Simulator146        <strong>"Connect":</strong> use this to connect developer
 > tools to the selected app. The Dashboard will start the Simulato
 >r and app if they aren't already running.
147      </li>
134      </li>148      <li>
149        <strong>"Remove" ("X"):</strong> use this to remove the a
 >pp from the Simulator and the Dashboard. You can undo this action
 > as long as the Dashboard tab is open.
135    </ul>150      </li>
151      <li>
152        <strong>"Receipt":</strong> use this to test receipt veri
 >fication for paid apps. After you select a type of receipt to tes
 >t, the app will be reinstalled with a test receipt of the given t
153      </li>
154    </ul>
155    <div class="note">
136    <p>156      <p>
137      If you've <a href="#Push-to-device" title="#Push-to-device"157        <strong>Refresh App from the Simulator window</strong>: y
>>connected a Firefox OS device</a> to your computer, you'll see a>ou can update and reload an app directly from the Simulator windo
> fourth command labeled "Push to device".>w <a href="#Simulator-menubar" title="#Simulator-menubar">using t
 >he menubar action or its associated shortcut</a> while the app is
 > running.
138    </p>158      </p>
159    </div>
n146      <li>manifest errors: problems that will prevent your app frn167      <li>manifest errors: problems that will prevent your app fr
>om running>om installing or running
nn190      <li>common appCache errors (packaged apps can't use appCach
 >e, requests to the manifest URL return an HTTP redirect or an HTT
 >P error status)
191      </li>
n172      <br>n
173      <img alt="" src="      <img alt="" src="
>shboard-missing-name.png">>shboard-missing-name-4.0.png" style="width: 1044px; height: 650px
n214      <li>if you add, update, or remove an app, or click the "Runn236      <li>if you add an app or click the "Refresh" or "Connect" b
>" button next to your app's entry, the Dashboard will automatical>utton next to your app's entry, the Dashboard will automatically 
>ly run your app in the Simulator>run your app in the Simulator
n222      The Simulator appears as a separate window, sized so the sin244      The Simulator appears as a separate window, sized so the si
>mulated screen area is 320x480 pixels, with a <a href="#Simulator>mulated screen area is 320x480 pixels, with a <a href="#Simulator
>-toolbar" title="#Simulator-toolbar">toolbar at the bottom that c>-toolbar" title="#Simulator-toolbar">toolbar at the bottom</a> an
>ontains some extra features</a>.>d a <a href="#Simulator-menubar" title="#Simulator-menubar">menub
 >ar at the top</a> that contains some extra features:
245    </p>
246    <p>
247      <img alt="" src="
 >mulator-bars.png" style="width: 1044px; height: 240px; margin-lef
 >t: auto; margin-right: auto; display: block;">
n228      <img alt="" src="      <img alt="" src="
>mulator-homescreen.png" style="width: 432px; height: 638px;float:>mulator-homescreen.png" style="width: 1044px; height: 666px;">
>left;"><img alt="" src=" 
>imulator-apps-screen.png" style="width: 432px; height: 638px;"> 
n234      You'll see three buttons on the toolbar at the bottom of thn259      In the bottom toolbar, from left to right, these are the <s
>e Simulator window:<br>>trong>Home button</strong>, the <strong>Screen Rotation button</s
 >trong>, and the <strong>Geolocation button</strong>.
260    </p>
261    <ul>
262      <li>the <strong>Home button</strong> takes you to the Home 
 >screen (or to the task list if you keep it pressed for a couple o
 >f seconds)
235      <br>263      </li>
236      <img alt="" src="      <li>the <strong>Screen Rotation button</strong> switches th
>mulator-toolbar.png" style="width: 415px; height: 190px; margin-l>e device between portrait and landscape orientation. This will ge
>eft: auto; margin-right: auto; display: block;">From left to righ>nerate the <a href="
>t, these are the Home button, the Rotation Simulation button, and>PI/Managing_screen_orientation#Listening_orientation_change" titl
> the Geolocation Simulation button.>e="/en-US/docs/WebAPI/Detecting_device_orientation">orientationch
 >ange</a> event.
237    </p>265      </li>
266      <li>the <strong>Geolocation button</strong> triggers a dial
 >og asking you to share your geographic location, either using you
 >r current coordinates or supplying custom coordinates: this will 
 >be made available to your app via the <a href="/en-US/docs/WebAPI
 >/Using_geolocation" title="/en-US/docs/WebAPI/Using_geolocation">
 >Geolocation API</a>.
267      </li>
238    <ul>268    </ul>
239      <li>the Home button takes you to the Home screen269    <p>
270      <a href="
 >geolocation.png" target="_blank"><img alt="" src="https://mdn.moz
 >" style="width:
 > 520px; height: 309px;"></a><a href="
 >/files/5519/simulator-screen-orientation.png" target="_blank"><im
 >g alt="" src="
 >creen-orientation.png" style="width: 500px; height: 297px;"></a>
271    </p>
272    <h3 id="Simulator_menubar">
273      <a name="Simulator-menubar" id="Simulator-menubar"></a>Simu
 >lator menubar
274    </h3>
275    <p>
276      In the top menubar, you can access some useful commands to 
 >make development more efficient:
277    </p>
278    <p>
279      <img alt="" src="
 >mulator-menubar.png" style="width: 1044px; height: 280px;">
280    </p>
281    <ul>
240      </li>282      <li>
241      <li>the Rotation Simulation button switches the device betw283        <strong>File -&gt; Quit</strong> (<em>Ctrl/Cmd - Q</em>):
>een portrait and landscape orientation. This will generate the <a> shut down the Simulator
> href="/en-US/docs/WebAPI/Detecting_device_orientation" title="/e 
>/a> event. 
284      </li>
242      </li>285      <li>
243      <li>the Geolocation Simulation button triggers a dialog ask286        <strong>App -&gt; Refresh</strong> (<em>Ctrl/Cmd - R</em>
>ing you to share your geographic location, either using your curr>): refresh the running app
>ent coordinates or supplying custom coordinates: this will be mad 
>e available to your app via the <a href="/en-US/docs/WebAPI/Using 
>_geolocation" title="/en-US/docs/WebAPI/Using_geolocation">Geoloc 
>ation API</a>. 
287      </li>
244      </li>288    </ul>
289    <p>
290      The keyboard shortcut for the <strong>"App Refresh"</strong
 >> command makes it possible to iteratively develop an app much li
 >ke a web page:
291    </p>
245    </ul>292    <ul>
246    <h3 id="Enabling_console_logging">293      <li>make a change to the code (and rerun your build tool if
 > needed, e.g. volo / yeoman / grunt)
247      Enabling console logging294      </li>
295      <li>type the keyboard shortcut to refresh the app running i
 >n the Simulator
296      </li>
248    </h3>297    </ul>
298    <div class="note">
249    <p>299      <p>
250      If you check the "Console" box underneath the "Stopped/Runn300        <strong>"Refresh App and Clear Data" hidden shortcut:</st
>ing" switch, then the <a href="/en-US/docs/Error_Console" title=">rong> sometimes it's useful to clear data that the Simulator has 
>/en-US/docs/Error_Console">Error Console</a> will be opened when >stored for an app, so the Simulator contains a hidden shortcut, <
>you run the Simulator. Your app will be able to log to this conso>em>Shift - Ctrl/Cmd - R</em>, that will refresh the running app w
>le using the global <a href="/en-US/docs/DOM/console" title="/en->hile clearing the following data:
>US/docs/DOM/console">console</a> object. 
251    </p>301      </p>
302      <ul>
303        <li>
304          <p>
305            localStorage / sessionStorage
306          </p>
307        </li>
308        <li>
309          <p>
310            cookies
311          </p>
312        </li>
313        <li>
314          <p>
315            indexedDB
316          </p>
317        </li>
318        <li>
319          <p>
320            appCache
321          </p>
322        </li>
323      </ul>
324    </div>
252    <h3 id="Attaching_developer_tools">325    <h2 id="Attaching_developer_tools">
n254    </h3>n327    </h2>
255    <p>
256      You can attach developer tools to the Simulator, to help de
>bug your app. At the moment you can only attach the <a href="/en- 
>US/docs/Tools/Debugger" title="/en-US/docs/Tools/Debugger">JavaSc 
>ript Debugger</a> and the <a href="/en-US/docs/Tools/Web_Console" 
> title="/en-US/docs/Tools/Web_Console">Web Console</a>, but we're 
> working on adding support for more developer tools. 
257    </p>328    <p>
329      You can attach developer tools to the Simulator, to help de
 >bug your app. At the moment you can only attach the <a href="/en-
 >US/docs/Tools/Debugger" title="/en-US/docs/Tools/Debugger">JavaSc
 >ript Debugger</a>, the <a href="/en-US/docs/Tools/Web_Console" ti
 >tle="/en-US/docs/Tools/Web_Console">Web Console</a>, the <a href=
 >"/en-US/docs/Tools/Style_Editor" title="/en-US/docs/Tools/Style_E
 >ditor">Style Editor</a>, the <a href="/en-US/docs/Tools/Profiler"
 > title="/en-US/docs/Tools/Profiler">Profiler</a> and the <a href=
 >"/en-US/docs/Tools/Network_Monitor" title="/en-US/docs/Tools/Netw
 >ork_Monitor">Network Monitor</a>, but we're working on adding sup
 >port for more <a href="
 >ools/DevTools_Window" title="
 >docs/Tools/DevTools_Window">developer tools</a>.
258    <p>330    </p>
259      While the Simulator is running another button appears under331    <div class="note">
>neath the "Console" checkbox. It is labeled "Connect...": 
332      <p>
333        Some of these tools are only available in Beta, Aurora, o
 >r Nightly builds of Firefox.
334      </p>
335    </div>
260    </p>336    <p>
337      To attach developer tools to the Simulator, click the <stro
 >ng>"Connect"</strong> button for an app:
261    <p>338    </p>
262      <img alt="" src="
>shboard-connect.png" style="width: 459px; height: 442px; margin-l 
>eft: auto; margin-right: auto; display: block;"> 
263    </p>339    <p>
340      <img alt="" src="
 >nnect-to-app-button.png" style="width: 1044px; height: 650px; mar
 >gin-left: auto; margin-right: auto; display: block;">
264    <p>341    </p>
265      Click it, and you'll be taken to a page that looks like thi
266    </p>342    <p>
343      The Dashboard will then open a developer toolbox pane at th
 >e bottom of the Dashboard tab and connect it to the app:
267    <p>344    </p>
268      <img alt="" src="
>nnect-port-selection.png" style="width: 798px; height: 718px; mar 
>gin-left: auto; margin-right: auto; display: block;">Click "Conne 
>ct" here and you'll see another page, this time like this:<br> 
269      <br>
270      <img alt="" src="
>nnect-target-selection.png" style="width: 798px; height: 718px; m 
>argin-left: auto; margin-right: auto; display: block;"> 
271    </p>345    <p>
346      <img alt="" src="
 >mulator-devtools-connected.png" style="width: 1044px; height: 750
 >px; margin-left: auto; margin-right: auto; display: block;">
272    <p>347    </p>
273      To use the <a href="/en-US/docs/Tools/Debugger" title="/en-348    <h3 id="Web_Console">
>US/docs/Tools/Debugger">JavaScript Debugger</a>, select "chrome:/ 
>/prosthesis/content/shell.xul" here. Once it's launched, you'll n 
>eed to find your app's scripts in the <a href="/en-US/docs/Tools/ 
>Debugger#The_debugger_toolbar" title="/en-US/docs/Tools/Debugger# 
>The_debugger_toolbar">script chooser</a>, but if you open your ap 
>p and then connect the debugger, your app's main script will be s 
>elected by default: 
349      Web Console
350    </h3>
274    </p>351    <p>
352      The app can log to this console using the global <a href="/
 >en-US/docs/DOM/console" title="/en-US/docs/DOM/console">console</
 >a> object, and it displays various other messages generated by th
 >e app: network requests, CSS and JS warnings/errors, and security
 > errors. (<a href="/en-US/docs/Tools/Web_Console" title="/en-US/d
 >ocs/Tools/Web_Console">Learn more about the Web Console.</a>)
275    <p>353    </p>
276      <img alt="" src="    <h3 id="Debugger">
>-debugger.png" style="width: 971px; height: 400px; margin-left: a 
>uto; margin-right: auto; display: block;"> To use the <a href="/e 
>n-US/docs/Tools/Web_Console" title="/en-US/docs/Tools/Web_Console 
>">Web Console</a> with your app, select "Main Process" in the "Co 
>nnect to remote device" window. 
355      Debugger
356    </h3>
277    </p>357    <p>
358      Using the Debugger, you can step through JavaScript code th
 >at is running in the connected app, manage breakpoints, and watch
 > expressions to track down errors and problems faster. (<a href="
 >/en-US/docs/Tools/Debugger" title="/en-US/docs/Tools/Web_Console"
 >>Learn more about the Debugger.</a>)
278    <p>359    </p>
279      At the moment, unfortunately, there's no single debugging t360    <h3 id="Style_Editor">
>arget that will work with both the Web Console and the JS Debugge 
>r - but you can run two simultaneous instances of the debugging t 
>ools, one targeting "shell.xul" and the other targeting "Main Pro 
361      Style Editor
362    </h3>
363    <p>
364      You can view and edit CSS files referenced in the app using
 > the connected Style Editor. Your changes will be applied to the 
 >app in real time, without needing to refresh the app. (<a href="/
 >en-US/docs/Tools/Style_Editor" title="/en-US/docs/Tools/Web_Conso
 >le">Learn more about the Style Editor.</a>)
365    </p>
366    <h3 id="Profiler">
367      Profiler
368    </h3>
369    <p>
370      Using the Profiler tool connected to the app, you can to fi
 >nd out where your JavaScript code is spending too much time. The 
 >Profiler periodically samples the current JavaScript call stack a
 >nd compiles statistics about the samples. (<a href="/en-US/docs/T
 >ools/Profiler" title="/en-US/docs/Tools/Web_Console">Learn more a
 >bout the Profiler.</a>)
371    </p>
372    <h3 id="Network_Monitor">
373      Network Monitor
374    </h3>
375    <p>
376      Thanks to the new Network Monitor, you can analyze the stat
 >us, headers, content and timing of all the network requests initi
 >ated by the app through a friendly interface. (<a href="https://h
 >" ti
 >efox-beta/">Learn more about the Network Monitor.</a>)
377    </p>
378    <h2 id="Receipts">
379      <a name="Simulator-receipts" id="Simulator-receipts"></a>Re
380    </h2>
381    <p>
382      If you are developing a paid app, you should test your rece
 >ipt validation code (e.g. the code that verifies that a user has 
 >already purchased the app or has been issued a refund and then in
 >forms the user and locks or unlocks app features accordingly) on 
 >a valid (cryptographically signed) receipt.
383    </p>
384    <p>
385      Thanks to the <strong>"Receipts"</strong> menu in each app 
 >entry on the Simulator Dashboard, you can install an app with a <
 >strong>"Valid"</strong>, <strong>"Invalid"</strong>, or <strong>"
 >Refunded"</strong> test receipt. Simply select the type of receip
 >t you wish to test, and the Dashboard will retrieve a test receip
 >t of that type from the Marketplace receipt service and reinstall
 > the app with that receipt in the Simulator:
386    </p>
387    <p>
388      <img alt="" src="
 >mulator-receipts-selector-4.0.png" style="width: 1044px; height: 
n291      To connect the device, follow the instructions in the guiden400      To connect the device, follow the instructions in the guide
> to <a href="/en-US/docs/Mozilla/Firefox_OS/Debugging/Connecting_> to <a href="/en-US/docs/Mozilla/Firefox_OS/Debugging/Connecting_
>a_Firefox_OS_device_to_the_desktop" title="/en-US/docs/Mozilla/Fi>a_Firefox_OS_device_to_the_desktop" title="/en-US/docs/Mozilla/Fi
>>connecting a Firefox OS device to the desktop</a>. Note that you>>connecting a Firefox OS device to the desktop</a>. Note that you
> don't have to install adb, as the Simulator add-on includes it a> don't have to install ADB, as the Simulator add-on includes it a
n297      Once you've set up the device and desktop, and connected thn406      Once you've set up the device and desktop, and connected th
>e device to your desktop via USB, you'll see the note "Device con>e device to your desktop via USB, you'll see the note <strong>"De
>nected." appear on the left of the Dashboard, and a new command a>vice connected"</strong> appear on the left of the Dashboard, and
>ppear in the entry for each app labeled "Push":> a new command appear in the entry for each app labeled <strong>"
298    </p>
299    <p>407    </p>
300      <img alt="" src="
301    </p>408    <p>
409      <img alt="" src="
 >mulator-push2device.png" style="width: 1044px; height: 620px;">
302    <p>410    </p>
411    <p>
303      Click "Push", and the app will be installed on the Firefox 412      Click <strong>"Push"</strong>, and the app will be installe
>OS device.>d on the Firefox OS device.
413    </p>
414    <div class="note">
415      <p>
416        <strong>Manual Steps:</strong>
417      </p>
418      <ul>
419        <li>
420          <p>
421            Once you’ve pushed the app to the device, you need to
 > manually close and restart it again, to get updated content
422          </p>
423        </li>
424        <li>
425          <p>
426            If you update anything in the manifest (e.g. app name
 >, orientation, type, permissions), you need to reboot the operati
 >ng system for those changes to have effect&nbsp;
427          </p>
428        </li>
429      </ul>
430    </div>
431    <h3 id="Firefox_OS_Device_Connection_Confirmation">
432      Firefox OS Device Connection Confirmation
433    </h3>
434    <p>
435      On every device reboot, the first <strong>"Push"</strong> r
 >equest needs to be confirmed on the device:
436    </p>
437    <p>
438      <img alt="" src="
 >vice-push-confirmation.png" style="width: 320px; height: 480px;">
n375      Getting helpn510      <a name="Simulator-help" id="Simulator-help"></a>Getting he
511    </h2>
512    <p>
513      The Firefox OS Simulator is still at an early stage of deve
 >lopment, and isn't yet as reliable and complete as we'd like it t
 >o be.
376    </h2>514    </p>
tt518    <h3 id="How_to_enable_verbose_logging">
519      <a name="Simulator-verbose-logging" id="Simulator-verbose-l
 >ogging"></a>How to enable verbose logging
520    </h3>
521    <p>
522      Use about:config to create the preference <a href="mailto:e
 ></a>, set it to the integer
 > value 0, and disable/reenable the addon. Additional messages abo
 >ut the Simulator's operation will appear in the Error Console (or
 > Browser Console in newer versions of Firefox).
523    </p>
524    <h3 id="How_to_get_the_latest_preview_build">
525      <a name="Simulator-latest-preview-build" id="Simulator-late
 >st-preview-build"></a>How to get the latest preview build
526    </h3>
527    <p>
528      The latest preview build can be downloaded from the followi
 >ng URLs:
529    </p>
530    <ul>
531      <li>Windows: <a href="
532      </li>
533      <li>Mac: <a href="
534      </li>
535      <li>Linux: <a href="
536      </li>
537    </ul>
538    <div class="warning">
539      <p>
540        Preview builds are less stable and complete than release 
 >builds, so use them with caution.
541      </p>
542    </div>

Back to History