{"id":14987961,"url":"https://github.com/apache/cordova-plugin-device-orientation","last_synced_at":"2025-05-16T05:04:20.110Z","repository":{"id":9085297,"uuid":"10860595","full_name":"apache/cordova-plugin-device-orientation","owner":"apache","description":"Apache Cordova Device Orientation Plugin","archived":false,"fork":false,"pushed_at":"2024-10-26T03:57:30.000Z","size":414,"stargazers_count":58,"open_issues_count":8,"forks_count":79,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-10T17:16:22.468Z","etag":null,"topics":["android","cordova","hacktoberfest","ios","java","javascript","library","mobile","nodejs","objective-c"],"latest_commit_sha":null,"homepage":"https://cordova.apache.org/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-06-22T07:00:15.000Z","updated_at":"2024-10-26T03:57:34.000Z","dependencies_parsed_at":"2024-11-16T16:27:39.643Z","dependency_job_id":"16a948e3-77eb-4745-957c-3952ba0ab2fd","html_url":"https://github.com/apache/cordova-plugin-device-orientation","commit_stats":{"total_commits":223,"total_committers":50,"mean_commits":4.46,"dds":0.7130044843049328,"last_synced_commit":"c91fe75a62a97645969d84c1d2db36530851d6c8"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcordova-plugin-device-orientation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcordova-plugin-device-orientation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcordova-plugin-device-orientation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcordova-plugin-device-orientation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/cordova-plugin-device-orientation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254046068,"owners_count":22005527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","cordova","hacktoberfest","ios","java","javascript","library","mobile","nodejs","objective-c"],"created_at":"2024-09-24T14:15:49.588Z","updated_at":"2025-05-16T05:04:20.088Z","avatar_url":"https://github.com/apache.png","language":"JavaScript","funding_links":[],"categories":["Index"],"sub_categories":[],"readme":"---\ntitle: Device Orientation\ndescription: Access compass data.\n---\n\u003c!---\n# license: Licensed to the Apache Software Foundation (ASF) under one\n#         or more contributor license agreements.  See the NOTICE file\n#         distributed with this work for additional information\n#         regarding copyright ownership.  The ASF licenses this file\n#         to you under the Apache License, Version 2.0 (the\n#         \"License\"); you may not use this file except in compliance\n#         with the License.  You may obtain a copy of the License at\n#\n#           http://www.apache.org/licenses/LICENSE-2.0\n#\n#         Unless required by applicable law or agreed to in writing,\n#         software distributed under the License is distributed on an\n#         \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n#         KIND, either express or implied.  See the License for the\n#         specific language governing permissions and limitations\n#         under the License.\n--\u003e\n\n# cordova-plugin-device-orientation\n\n[![Android Testsuite](https://github.com/apache/cordova-plugin-device-orientation/actions/workflows/android.yml/badge.svg)](https://github.com/apache/cordova-plugin-device-orientation/actions/workflows/android.yml) [![Chrome Testsuite](https://github.com/apache/cordova-plugin-device-orientation/actions/workflows/chrome.yml/badge.svg)](https://github.com/apache/cordova-plugin-device-orientation/actions/workflows/chrome.yml) [![iOS Testsuite](https://github.com/apache/cordova-plugin-device-orientation/actions/workflows/ios.yml/badge.svg)](https://github.com/apache/cordova-plugin-device-orientation/actions/workflows/ios.yml) [![Lint Test](https://github.com/apache/cordova-plugin-device-orientation/actions/workflows/lint.yml/badge.svg)](https://github.com/apache/cordova-plugin-device-orientation/actions/workflows/lint.yml)\n\n# Usage Notice\n\nWith the [W3C Device Orientation API](https://www.w3.org/TR/orientation-event/), Android, iOS, and Windows devices may not need this plugin anymore.\n\nHowever, on iOS 13+, potential issues with permissions and secure contexts can arise. Therefore it is recommended to use this plugin as it uses a native implementation.\n\n------\n\n## Description\n\nThis plugin provides access to the device's compass. The compass is a sensor\nthat detects the direction or heading that the device is pointed, typically\nfrom the top of the device.  It measures the heading in degrees from 0 to\n359.99, where 0 is north.\n\nAccess is via a global `navigator.compass` object.\n\nAlthough the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event.\n\n    document.addEventListener(\"deviceready\", onDeviceReady, false);\n    function onDeviceReady() {\n        console.log(navigator.compass);\n    }\n\nReport issues on the [Apache Cordova issue tracker](https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=190\u0026projectKey=CB)\n\n## Installation\n\n    cordova plugin add cordova-plugin-device-orientation\n\n## Supported Platforms\n\n- Android\n- Browser\n- iOS\n- Windows\n\n## Methods\n\n- navigator.compass.getCurrentHeading\n- navigator.compass.watchHeading\n- navigator.compass.clearWatch\n\n## navigator.compass.getCurrentHeading\n\nGet the current compass heading. The compass heading is returned via a `CompassHeading`\nobject using the `compassSuccess` callback function.\n\n    navigator.compass.getCurrentHeading(compassSuccess, compassError);\n\n### Example\n\n    function onSuccess(heading) {\n        alert('Heading: ' + heading.magneticHeading);\n    };\n\n    function onError(error) {\n        alert('CompassError: ' + error.code);\n    };\n\n    navigator.compass.getCurrentHeading(onSuccess, onError);\n\n## navigator.compass.watchHeading\n\nGets the device's current heading at a regular interval. Each time the heading\nis retrieved, the `headingSuccess` callback function is executed.\n\nThe returned watch ID references the compass watch interval. The watch\nID can be used with `navigator.compass.clearWatch` to stop watching the navigator.compass.\n\n    var watchID = navigator.compass.watchHeading(compassSuccess, compassError, [compassOptions]);\n\n`compassOptions` may contain the following keys:\n\n- __frequency__: How often to retrieve the compass heading in milliseconds. _(Number)_ (Default: 100)\n- __filter__: The change in degrees required to initiate a watchHeading success callback. When this value is set, __frequency__ is ignored. _(Number)_\n\n### Example\n\n    function onSuccess(heading) {\n        var element = document.getElementById('heading');\n        element.innerHTML = 'Heading: ' + heading.magneticHeading;\n    };\n\n    function onError(compassError) {\n        alert('Compass error: ' + compassError.code);\n    };\n\n    var options = {\n        frequency: 3000\n    }; // Update every 3 seconds\n\n    var watchID = navigator.compass.watchHeading(onSuccess, onError, options);\n\n\n### Browser Quirks\n\nValues for current heading are randomly generated in order to simulate the compass.\n\n### iOS Quirks\n\nOnly one `watchHeading` can be in effect at one time in iOS.  If a\n`watchHeading` uses a filter, calling `getCurrentHeading` or\n`watchHeading` uses the existing filter value to specify heading\nchanges. Watching heading changes with a filter is more efficient than\nwith time intervals.\n\n### Android Quirks\n\n- No support for `filter`.\n\n## navigator.compass.clearWatch\n\nStop watching the compass referenced by the watch ID parameter.\n\n    navigator.compass.clearWatch(watchID);\n\n- __watchID__: The ID returned by `navigator.compass.watchHeading`.\n\n### Example\n\n    var watchID = navigator.compass.watchHeading(onSuccess, onError, options);\n\n    // ... later on ...\n\n    navigator.compass.clearWatch(watchID);\n\n## CompassHeading\n\nA `CompassHeading` object is returned to the `compassSuccess` callback function.\n\n### Properties\n\n- __magneticHeading__: The heading in degrees from 0-359.99 at a single moment in time. _(Number)_\n\n- __trueHeading__: The heading relative to the geographic North Pole in degrees 0-359.99 at a single moment in time. A negative value indicates that the true heading can't be determined.  _(Number)_\n\n- __headingAccuracy__: The deviation in degrees between the reported heading and the true heading. _(Number)_\n\n- __timestamp__: The time at which this heading was determined.  _(DOMTimeStamp)_\n\n### Android Quirks\n\n- The `trueHeading` property is not supported, but reports the same value as `magneticHeading`.\n\n- The `headingAccuracy` property is always 0 because there is no difference between the `magneticHeading` and `trueHeading`.\n\n### iOS Quirks\n\n- The `trueHeading` property is only returned for location services enabled via `navigator.geolocation.watchLocation()`.\n\n## CompassError\n\nA `CompassError` object is returned to the `compassError` callback function when an error occurs.\n\n### Properties\n\n- __code__: One of the predefined error codes listed below.\n\n### Constants\n\n- `CompassError.COMPASS_INTERNAL_ERR`\n- `CompassError.COMPASS_NOT_SUPPORTED`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fcordova-plugin-device-orientation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fcordova-plugin-device-orientation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fcordova-plugin-device-orientation/lists"}