Skip to content

Commit 19c78e3

Browse files
Krzysztof Ciomborhramos
Krzysztof Ciombor
authored and
hramos
committed
Add docs for building for Android TV and unify them with Apple TV docs (#59)
1 parent 3aa2651 commit 19c78e3

3 files changed

Lines changed: 242 additions & 14 deletions

File tree

‎docs/building-for-apple-tv.md‎

Lines changed: 240 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,85 @@
11
---
2-
id: building-for-apple-tv
3-
title: Building For Apple TV
2+
id: building-for-tv-devices
3+
title: Building For TV Devices
44
---
55

6-
Apple TV support has been implemented with the intention of making existing React Native iOS applications "just work" on tvOS, with few or no changes needed in the JavaScript code for the applications.
6+
<style>
7+
.toggler li {
8+
display: inline-block;
9+
position: relative;
10+
top: 1px;
11+
padding: 10px;
12+
margin: 0px 2px 0px 2px;
13+
border: 1px solid #05A5D1;
14+
border-bottom-color: transparent;
15+
border-radius: 3px 3px 0px 0px;
16+
color: #05A5D1;
17+
background-color: transparent;
18+
font-size: 0.99em;
19+
cursor: pointer;
20+
}
21+
.toggler li:first-child {
22+
margin-left: 0;
23+
}
24+
.toggler li:last-child {
25+
margin-right: 0;
26+
}
27+
.toggler ul {
28+
width: 100%;
29+
display: inline-block;
30+
list-style-type: none;
31+
margin: 0;
32+
border-bottom: 1px solid #05A5D1;
33+
cursor: default;
34+
}
35+
@media screen and (max-width: 960px) {
36+
.toggler li,
37+
.toggler li:first-child,
38+
.toggler li:last-child {
39+
display: block;
40+
border-bottom-color: #05A5D1;
41+
border-radius: 3px;
42+
margin: 2px 0px 2px 0px;
43+
}
44+
.toggler ul {
45+
border-bottom: 0;
46+
}
47+
}
48+
.toggler a {
49+
display: inline-block;
50+
padding: 10px 5px;
51+
margin: 2px;
52+
border: 1px solid #05A5D1;
53+
border-radius: 3px;
54+
text-decoration: none !important;
55+
}
56+
.display-platform-ios .toggler .button-ios,
57+
.display-platform-android .toggler .button-android {
58+
background-color: #05A5D1;
59+
color: white;
60+
}
61+
block { display: none; }
62+
.display-platform-ios .ios,
63+
.display-platform-android .android {
64+
display: block;
65+
}
66+
</style>
67+
68+
TV devices support has been implemented with the intention of making existing React Native applications "just work" on Apple TV and Android TV, with few or no changes needed in the JavaScript code for the applications.
69+
70+
<div class="toggler">
71+
72+
<ul role="tablist" >
73+
<li id="ios" class="button-ios" aria-selected="false" role="tab" tabindex="0" aria-controls="iostab" onclick="displayTab('platform', 'ios')">
74+
iOS
75+
</li>
76+
<li id="android" class="button-android" aria-selected="false" role="tab" tabindex="-1" aria-controls="androidtab" onclick="displayTab('platform', 'android')">
77+
Android
78+
</li>
79+
</ul>
80+
</div>
81+
82+
<block class="ios" />
783

884
The RNTester app supports Apple TV; use the `RNTester-tvOS` build target to build for tvOS.
985

@@ -17,22 +93,75 @@ The RNTester app supports Apple TV; use the `RNTester-tvOS` build target to buil
1793

1894
```javascript
1995
var Platform = require('Platform');
20-
var running_on_apple_tv = Platform.isTVOS;
96+
var running_on_tv = Platform.isTV;
97+
98+
// If you want to be more specific and only detect devices running tvOS
99+
// (but no Android TV devices) you can use:
100+
var running_on_apple_tv = Platform.isTVOS
101+
```
102+
103+
<block class="android" />
104+
105+
## Build changes
106+
107+
* _Native layer_: To run React Native project on Android TV make sure to make the following changes to `AndroidManifest.xml`
108+
109+
```xml
110+
<!-- Add custom banner image to display as Android TV launcher icon -->
111+
<application
112+
...
113+
android:banner="@drawable/tv_banner"
114+
>
115+
...
116+
<intent-filter>
117+
...
118+
<!-- Needed to properly create a launch intent when running on Android TV -->
119+
<category android:name="android.intent.category.LEANBACK_LAUNCHER"/>
120+
</intent-filter>
121+
...
122+
</application>
21123
```
22124

125+
* _JavaScript layer_: Support for Android TV has been added to `Platform.android.js`. You can check whether code is running on Android TV by doing
126+
127+
```js
128+
var Platform = require('Platform');
129+
var running_on_android_tv = Platform.isTV;
130+
```
131+
132+
<block class="ios android" />
133+
23134
## Code changes
24135

25-
* _General support for tvOS_: Apple TV specific changes in native code are all wrapped by the TARGET_OS_TV define. These include changes to suppress APIs that are not supported on tvOS (e.g. web views, sliders, switches, status bar, etc.), and changes to support user input from the TV remote or keyboard.
136+
<block class="ios" />
137+
138+
* _General support for tvOS_: Apple TV specific changes in native code are all wrapped by the TARGET_OS_TV define. These include changes to suppress APIs that are not supported on tvOS (e.g. web views, sliders, switches, status bar, etc.), and changes to support user input from the TV remote or keyboard.
139+
140+
* _Common codebase_: Since tvOS and iOS share most Objective-C and JavaScript code in common, most documentation for iOS applies equally to tvOS.
26141

27-
* _Common codebase_: Since tvOS and iOS share most Objective-C and JavaScript code in common, most documentation for iOS applies equally to tvOS.
142+
* _Access to touchable controls_: When running on Apple TV, the native view class is `RCTTVView`, which has additional methods to make use of the tvOS focus engine. The `Touchable` mixin has code added to detect focus changes and use existing methods to style the components properly and initiate the proper actions when the view is selected using the TV remote, so `TouchableHighlight` and `TouchableOpacity` will "just work". In particular:
28143

29-
* _Access to touchable controls_: When running on Apple TV, the native view class is `RCTTVView`, which has additional methods to make use of the tvOS focus engine. The `Touchable` mixin has code added to detect focus changes and use existing methods to style the components properly and initiate the proper actions when the view is selected using the TV remote, so `TouchableHighlight` and `TouchableOpacity` will "just work". In particular:
144+
* `touchableHandleActivePressIn` will be executed when the touchable view goes into focus
145+
* `touchableHandleActivePressOut` will be executed when the touchable view goes out of focus
146+
* `touchableHandlePress` will be executed when the touchable view is actually selected by pressing the "select" button on the TV remote.
147+
148+
<block class="android" />
149+
150+
* _Access to touchable controls_: When running on Android TV the Android framework will automatically apply a directional navigation scheme based on relative position of focusable elements in your views. The `Touchable` mixin has code added to detect focus changes and use existing methods to style the components properly and initiate the proper actions when the view is selected using the TV remote, so `TouchableHighlight`, `TouchableOpacity` and `TouchableNativeFeedback` will "just work". In particular:
30151

31152
* `touchableHandleActivePressIn` will be executed when the touchable view goes into focus
32153
* `touchableHandleActivePressOut` will be executed when the touchable view goes out of focus
33154
* `touchableHandlePress` will be executed when the touchable view is actually selected by pressing the "select" button on the TV remote.
34155

35-
* _TV remote/keyboard input_: A new native class, `RCTTVRemoteHandler`, sets up gesture recognizers for TV remote events. When TV remote events occur, this class fires notifications that are picked up by `RCTTVNavigationEventEmitter` (a subclass of `RCTEventEmitter`), that fires a JS event. This event will be picked up by instances of the `TVEventHandler` JavaScript object. Application code that needs to implement custom handling of TV remote events can create an instance of `TVEventHandler` and listen for these events, as in the following code:
156+
<block class="ios" />
157+
158+
* _TV remote/keyboard input_: A new native class, `RCTTVRemoteHandler`, sets up gesture recognizers for TV remote events. When TV remote events occur, this class fires notifications that are picked up by `RCTTVNavigationEventEmitter` (a subclass of `RCTEventEmitter`), that fires a JS event. This event will be picked up by instances of the `TVEventHandler` JavaScript object. Application code that needs to implement custom handling of TV remote events can create an instance of `TVEventHandler` and listen for these events, as in the following code:
159+
160+
<block class="android">
161+
162+
* _TV remote/keyboard input_: A new native class, `ReactAndroidTVRootViewHelper`, sets up key events handlers for TV remote events. When TV remote events occur, this class fires a JS event. This event will be picked up by instances of the `TVEventHandler` JavaScript object. Application code that needs to implement custom handling of TV remote events can create an instance of `TVEventHandler` and listen for these events, as in the following code:
163+
164+
<block class="ios android">
36165

37166
```javascript
38167
var TVEventHandler = require('TVEventHandler');
@@ -77,14 +206,113 @@ class Game2048 extends React.Component {
77206
}
78207
```
79208
80-
* _Dev Menu support_: On the simulator, cmd-D will bring up the developer menu, just like on iOS. To bring it up on a real Apple TV device, make a long press on the play/pause button on the remote. (Please do not shake the Apple TV device, that will not work :) )
209+
<block class="ios" />
81210
82-
* _TV remote animations_: `RCTTVView` native code implements Apple-recommended parallax animations to help guide the eye as the user navigates through views. The animations can be disabled or adjusted with new optional view properties.
211+
* _Dev Menu support_: On the simulator, cmd-D will bring up the developer menu, just like on iOS. To bring it up on a real Apple TV device, make a long press on the play/pause button on the remote. (Please do not shake the Apple TV device, that will not work :) )
212+
213+
* _TV remote animations_: `RCTTVView` native code implements Apple-recommended parallax animations to help guide the eye as the user navigates through views. The animations can be disabled or adjusted with new optional view properties.
83214
84215
* _Back navigation with the TV remote menu button_: The `BackHandler` component, originally written to support the Android back button, now also supports back navigation on the Apple TV using the menu button on the TV remote.
85216
86-
* _TabBarIOS behavior_: The `TabBarIOS` component wraps the native `UITabBar` API, which works differently on Apple TV. To avoid jittery rerendering of the tab bar in tvOS (see [this issue](https://github.com/facebook/react-native/issues/15081)), the selected tab bar item can only be set from Javascript on initial render, and is controlled after that by the user through native code.
217+
* _TabBarIOS behavior_: The `TabBarIOS` component wraps the native `UITabBar` API, which works differently on Apple TV. To avoid jittery rerendering of the tab bar in tvOS (see [this issue](https://github.com/facebook/react-native/issues/15081)), the selected tab bar item can only be set from Javascript on initial render, and is controlled after that by the user through native code.
218+
219+
<block class="android" />
220+
221+
* _Dev Menu support_: On the simulator, cmd-M will bring up the developer menu, just like on Android. To bring it up on a real Android TV device, make a long press on the play/pause button on the remote. (Please do not shake the Android TV device, that will not work :) )
222+
223+
<block class="ios" />
224+
225+
* _Known issues_:
226+
227+
* [ListView scrolling](https://github.com/facebook/react-native/issues/12793). The issue can be easily worked around by setting `removeClippedSubviews` to false in ListView and similar components. For more discussion of this issue, see [this PR](https://github.com/facebook/react-native/pull/12944).
228+
229+
<block class="android" />
87230
88231
* _Known issues_:
89232
90-
* [ListView scrolling](https://github.com/facebook/react-native/issues/12793). The issue can be easily worked around by setting `removeClippedSubviews` to false in ListView and similar components. For more discussion of this issue, see [this PR](https://github.com/facebook/react-native/pull/12944).
233+
* `InputText` components do not work for now (i.e. they cannot receive focus).
234+
235+
<script>
236+
function displayTab(type, value) {
237+
var container = document.getElementsByTagName('block')[0].parentNode;
238+
container.className = 'display-' + type + '-' + value + ' ' +
239+
container.className.replace(RegExp('display-' + type + '-[a-z]+ ?'), '');
240+
}
241+
function convertBlocks() {
242+
// Convert <div>...<span><block /></span>...</div>
243+
// Into <div>...<block />...</div>
244+
var blocks = document.querySelectorAll('block');
245+
for (var i = 0; i < blocks.length; ++i) {
246+
var block = blocks[i];
247+
var span = blocks[i].parentNode;
248+
var container = span.parentNode;
249+
container.insertBefore(block, span);
250+
container.removeChild(span);
251+
}
252+
// Convert <div>...<block />content<block />...</div>
253+
// Into <div>...<block>content</block><block />...</div>
254+
blocks = document.querySelectorAll('block');
255+
for (var i = 0; i < blocks.length; ++i) {
256+
var block = blocks[i];
257+
while (
258+
block.nextSibling &&
259+
block.nextSibling.tagName !== 'BLOCK'
260+
) {
261+
block.appendChild(block.nextSibling);
262+
}
263+
}
264+
}
265+
function guessPlatformAndOS() {
266+
if (!document.querySelector('block')) {
267+
return;
268+
}
269+
// If we are coming to the page with a hash in it (i.e. from a search, for example), try to get
270+
// us as close as possible to the correct platform and dev os using the hashtag and block walk up.
271+
var foundHash = false;
272+
if (
273+
window.location.hash !== '' &&
274+
window.location.hash !== 'content'
275+
) {
276+
// content is default
277+
var hashLinks = document.querySelectorAll(
278+
'a.hash-link'
279+
);
280+
for (
281+
var i = 0;
282+
i < hashLinks.length && !foundHash;
283+
++i
284+
) {
285+
if (hashLinks[i].hash === window.location.hash) {
286+
var parent = hashLinks[i].parentElement;
287+
while (parent) {
288+
if (parent.tagName === 'BLOCK') {
289+
// Could be more than one target os and dev platform, but just choose some sort of order
290+
// of priority here.
291+
// Target Platform
292+
if (parent.className.indexOf('ios') > -1) {
293+
displayTab('platform', 'ios');
294+
foundHash = true;
295+
} else if (
296+
parent.className.indexOf('android') > -1
297+
) {
298+
displayTab('platform', 'android');
299+
foundHash = true;
300+
} else {
301+
break;
302+
}
303+
}
304+
parent = parent.parentElement;
305+
}
306+
}
307+
}
308+
}
309+
// Do the default if there is no matching hash
310+
if (!foundHash) {
311+
var isMac = navigator.platform === 'MacIntel';
312+
var isWindows = navigator.platform === 'Win32';
313+
displayTab('platform', isMac ? 'ios' : 'android');
314+
}
315+
}
316+
convertBlocks();
317+
guessPlatformAndOS();
318+
</script>

‎website/i18n/en.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
"asyncstorage": "AsyncStorage",
2222
"backandroid": "BackAndroid",
2323
"backhandler": "BackHandler",
24-
"building-for-apple-tv": "Building For Apple TV",
24+
"building-for-tv-devices": "Building For TV Devices",
2525
"button": "Button",
2626
"cameraroll": "CameraRoll",
2727
"checkbox": "CheckBox",

‎website/sidebars.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
"direct-manipulation",
3232
"colors",
3333
"integration-with-existing-apps",
34+
"building-for-tv-devices",
3435
"running-on-device",
3536
"upgrading",
3637
"troubleshooting"
@@ -41,7 +42,6 @@
4142
"linking-libraries-ios",
4243
"running-on-simulator-ios",
4344
"communication-ios",
44-
"building-for-apple-tv",
4545
"app-extensions"
4646
],
4747
"Guides (Android)": [

0 commit comments

Comments
 (0)