@exodus/react-native-webview 11.26.1-exodus.6 → 11.26.1-exodus.7

package/docs/Custom-iOS.md

@@ -0,0 +1,236 @@
+**NOTE: This document was imported from [the original WebView documentation](https://github.com/facebook/react-native-website/blob/7d3e9e120e38a7ba928f6b173eb98f88b6f2f85f/docs/custom-webview-ios.md). While it may prove useful, it has not been adapted to React Native WebView yet.**
+
+While the built-in web view has a lot of features, it is not possible to handle every use-case in React Native. You can, however, extend the web view with native code without forking React Native or duplicating all the existing web view code.
+
+Before you do this, you should be familiar with the concepts in [native UI components](native-components-ios). You should also familiarise yourself with the [native code for web views](https://github.com/react-native-webview/react-native-webview/blob/master/apple/RNCWebViewManager.m), as you will have to use this as a reference when implementing new features—although a deep understanding is not required.
+
+## Native Code
+
+Like for regular native components, you need a view manager and an web view.
+
+For the view, you'll need to make a subclass of `RCTWebView`.
+
+```objc
+// RCTCustomWebView.h
+#import <React/RCTWebView.h>
+
+@interface RCTCustomWebView : RCTWebView
+
+@end
+
+// RCTCustomWebView.m
+#import "RCTCustomWebView.h"
+
+@interface RCTCustomWebView ()
+
+@end
+
+@implementation RCTCustomWebView { }
+
+@end
+```
+
+For the view manager, you need to make a subclass `RCTWebViewManager`. You must still include:
+
+* `(UIView *)view` that returns your custom view
+* The `RCT_EXPORT_MODULE()` tag
+
+```objc
+// RCTCustomWebViewManager.h
+#import <React/RCTWebViewManager.h>
+
+@interface RCTCustomWebViewManager : RCTWebViewManager
+
+@end
+
+// RCTCustomWebViewManager.m
+#import "RCTCustomWebViewManager.h"
+#import "RCTCustomWebView.h"
+
+@interface RCTCustomWebViewManager () <RCTWebViewDelegate>
+
+@end
+
+@implementation RCTCustomWebViewManager { }
+
+RCT_EXPORT_MODULE()
+
+- (UIView *)view
+{
+  RCTCustomWebView *webView = [RCTCustomWebView new];
+  webView.delegate = self;
+  return webView;
+}
+
+@end
+```
+
+### Adding New Events and Properties
+
+Adding new properties and events is the same as regular UI components. For properties, you define an `@property` in the header. For events, you define a `RCTDirectEventBlock` in the view's `@interface`.
+
+```objc
+// RCTCustomWebView.h
+@property (nonatomic, copy) NSString *finalUrl;
+
+// RCTCustomWebView.m
+@interface RCTCustomWebView ()
+
+@property (nonatomic, copy) RCTDirectEventBlock onNavigationCompleted;
+
+@end
+```
+
+Then expose it in the view manager's `@implementation`.
+
+```objc
+// RCTCustomWebViewManager.m
+RCT_EXPORT_VIEW_PROPERTY(onNavigationCompleted, RCTDirectEventBlock)
+RCT_EXPORT_VIEW_PROPERTY(finalUrl, NSString)
+```
+
+### Extending Existing Events
+
+You should refer to [RCTWebView.m](https://github.com/facebook/react-native/blob/master/React/Views/RCTWebView.m) in the React Native codebase to see what handlers are available and how they are implemented. You can extend any methods here to provide extra functionality.
+
+By default, most methods aren't exposed from RCTWebView. If you need to expose them, you need to create an [Objective C category](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/CustomizingExistingClasses/CustomizingExistingClasses.html), and then expose all the methods you need to use.
+
+```objc
+// RCTWebView+Custom.h
+#import <React/RCTWebView.h>
+
+@interface RCTWebView (Custom)
+- (BOOL)webView:(__unused UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType;
+- (NSMutableDictionary<NSString *, id> *)baseEvent;
+@end
+```
+
+Once these are exposed, you can reference them in your custom web view class.
+
+```objc
+// RCTCustomWebView.m
+
+// Remember to import the category file.
+#import "RCTWebView+Custom.h"
+
+- (BOOL)webView:(__unused UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request
+ navigationType:(UIWebViewNavigationType)navigationType
+{
+  BOOL allowed = [super webView:webView shouldStartLoadWithRequest:request navigationType:navigationType];
+
+  if (allowed) {
+    NSString* url = request.URL.absoluteString;
+    if (url && [url isEqualToString:_finalUrl]) {
+      if (_onNavigationCompleted) {
+        NSMutableDictionary<NSString *, id> *event = [self baseEvent];
+        _onNavigationCompleted(event);
+      }
+    }
+  }
+
+  return allowed;
+}
+```
+
+### Setting Client Certificate Authentication Credential
+
+If you open webpages that needs a Client Certificate for Authentication, you can create a credential and pass it to the webview:
+
+```
+[RNCWebView setClientAuthenticationCredential:credential];
+```
+
+This can be paired with a call from Javascript to pass a string label for the certificate stored in keychain and use native calls to fetch the certificate to create a credential object. This call can be made anywhere that makes sense for your application (e.g. as part of the user authentication stack). The only requirement is to make this call before displaying any webviews.
+
+### Allowing custom CAs (Certifica Authorities) and enabling SSL Pinning
+
+If you need to connect to a server which has a self signed certificate, or want to perform SSL Pinning on the webview requests, you need to pass a dictionary with the host as the key, and the certificate as the value of each item:
+
+
+```objc
+-(void)installCerts {
+
+  // Get the bundle where the certificates in DER format are present.
+  NSBundle *bundle = [NSBundle mainBundle];
+  
+  NSMutableDictionary* certMap = [NSMutableDictionary new];
+
+  NSData *rootCertData = [NSData dataWithContentsOfFile:[bundle pathForResource:@"example_ca" ofType:@"der"]];
+
+  SecCertificateRef certificate = SecCertificateCreateWithData(NULL, (CFDataRef) rootCertData);
+   
+  OSStatus err = SecItemAdd((CFDictionaryRef) [NSDictionary dictionaryWithObjectsAndKeys:(id) kSecClassCertificate, kSecClass, certificate, kSecValueRef, nil], NULL);
+  
+  [certMap setObject:(__bridge id _Nonnull)(certificate) forKey:@"example.com"];
+
+  [RNCWebView setCustomCertificatesForHost:certMap];
+}
+
+```
+
+Multiple hosts can be added to the dictionary, and only one certificate for a host is allowed. The verification will succeed if any of the certificates in the chain of the request matches the one defined for the request's host.
+
+
+## JavaScript Interface
+
+To use your custom web view, you may want to create a class for it. Your class must return a `WebView` component with the prop `nativeConfig.component` set to your native component (see below).
+
+To get your native component, you must use `requireNativeComponent`: the same as for regular custom components.
+
+```javascript
+import React, {Component} from 'react';
+import {WebView, requireNativeComponent, NativeModules} from 'react-native';
+const {CustomWebViewManager} = NativeModules;
+
+export default class CustomWebView extends Component {
+  render() {
+    return (
+      <WebView
+        {...this.props}
+        nativeConfig={{
+          component: RCTCustomWebView,
+          viewManager: CustomWebViewManager,
+        }}
+      />
+    );
+  }
+}
+
+const RCTCustomWebView = requireNativeComponent('RCTCustomWebView');
+```
+
+If you want to add custom props to your native component, you can use `nativeConfig.props` on the web view. For iOS, you should also set the `nativeConfig.viewManager` prop with your custom WebView ViewManager as in the example above.
+
+For events, the event handler must always be set to a function. This means it isn't safe to use the event handler directly from `this.props`, as the user might not have provided one. The standard approach is to create a event handler in your class, and then invoking the event handler given in `this.props` if it exists.
+
+If you are unsure how something should be implemented from the JS side, look at [WebView.ios.tsx](https://github.com/react-native-webview/react-native-webview/blob/master/src/WebView.ios.tsx) in the React Native WebView source.
+
+```javascript
+export default class CustomWebView extends Component {
+  _onNavigationCompleted = (event) => {
+    const {onNavigationCompleted} = this.props;
+    onNavigationCompleted && onNavigationCompleted(event);
+  };
+
+  render() {
+    return (
+      <WebView
+        {...this.props}
+        nativeConfig={{
+          component: RCTCustomWebView,
+          props: {
+            finalUrl: this.props.finalUrl,
+            onNavigationCompleted: this._onNavigationCompleted,
+          },
+          viewManager: CustomWebViewManager,
+        }}
+      />
+    );
+  }
+}
+```
+## Translations
+
+This file is available at:
+
+- [Brazilian portuguese](Custom-iOS.portuguese.md)

package/docs/Debugging.md

@@ -0,0 +1,101 @@
+# React Native WebView Debugging Guide
+
+Here are some helpful React Native WebView debugging tips.
+
+## Script Errors
+
+It can be difficult to debug syntax errors and other script errors in WebView, since errors don't show up in a console by default.
+
+One option (if you're loading HTML from an external source) is to inject an error handler before the content is loaded.
+
+```js
+<WebView
+  injectedJavaScriptBeforeContentLoaded={`
+    window.onerror = function(message, sourcefile, lineno, colno, error) {
+      alert("Message: " + message + " - Source: " + sourcefile + " Line: " + lineno + ":" + colno);
+      return true;
+    };
+    true;
+  `}
+  source={{
+    uri:
+      'https://bl.ocks.org/jamonholmgren/raw/48423fd99537283beace1daa2688e80f/',
+  }}
+/>
+```
+
+This will provide an Alert box with (hopefully) useful debugging information.
+
+If you're injecting JavaScript, this may fail with `Script error` and no other useful information. One simple way to debug this is to wrap your injected JavaScript in a try/catch, like so:
+
+```js
+const js = `
+  try {
+    // your code here
+  } catch(e) {
+    alert(e)
+  }
+  true;
+`;
+```
+
+This will bring up an alert with the error message, which may or may not be helpful.
+
+If these two simple methods fail to uncover the bug, try using the next technique!
+
+## Debugging WebView Contents
+
+### iOS & Safari
+
+It's possible to debug WebView contents in the iOS simulator or on a device using Safari Developer Toolkit.
+
+#### Steps:
+
+1. Open Safari Preferences -> "Advanced" tab -> enable checkbox "Show Develop menu in menu bar"
+2. Start app with React Native WebView in iOS simulator or iOS device
+3. Safari -> Develop -> [device name] -> [app name] -> [url - title]
+4. You can now debug the WebView contents just as you would on the web
+
+##### Notes:
+
+When debugging on device you must enable Web Inspector in your device settings:
+
+Settings -> Safari -> Advanced -> Web Inspector
+
+Also, if you don't see your device in the Develop menu, and you started Safari before you started your simulator, try restarting Safari.
+
+### Android & Chrome
+
+It's possible to debug WebView contents in the Android emulator or on a device using Chrome DevTools.
+
+1. You will need to make the following change to `MainApplication.java` to enabled web contents debugging:
+
+```java
+  import android.webkit.WebView;
+
+  @Override
+  public void onCreate() {
+    super.onCreate();
+	  ...
+    WebView.setWebContentsDebuggingEnabled(true);
+  }
+```
+
+2. Start app with React Native WebView in Android emulator or Android device
+3. Open `chrome://inspect/#devices` on Chrome (Reference: [Remote debug Android devices](https://developer.chrome.com/docs/devtools/remote-debugging/))
+4. Select your device on the left and select "Inspect" on the WebView contents you'd like to inspect
+5. You can now debug the WebView contents just as you would on the web
+
+![image](https://user-images.githubusercontent.com/1479215/47129785-9476e480-d24b-11e8-8cb1-fba77ee1c072.png)
+
+##### Note:
+
+When debugging on device you must enable USB debugging in your device settings:
+
+Settings -> System -> About Phone -> Developer options -> enable USB debugging
+
+## Translations
+
+This file is available at:
+
+- [Brazilian portuguese](Debugging.portuguese.md)

package/docs/Getting-Started.md

@@ -0,0 +1,142 @@
+# React Native WebView Getting Started Guide
+
+Here's how to get started quickly with the React Native WebView.
+
+## 1. Add react-native-webview to your dependencies
+
+```
+$ yarn add react-native-webview
+```
+
+(or)
+
+For npm use
+
+```
+$ npm install --save react-native-webview
+```
+
+## 2. Link native dependencies
+
+From react-native 0.60 autolinking will take care of the link step but don't forget to run `pod install`
+
+React Native modules that include native Objective-C, Swift, Java, or Kotlin code have to be "linked" so that the compiler knows to include them in the app.
+
+```
+$ react-native link react-native-webview
+```
+
+_NOTE: If you ever need to uninstall React Native WebView, run `react-native unlink react-native-webview` to unlink it._
+
+### iOS & macOS:
+
+If using CocoaPods, in the `ios/` or `macos/` directory run:
+
+```
+$ pod install
+```
+
+While you can manually link the old way using [react-native own tutorial](https://reactnative.dev/docs/linking-libraries-ios), we find it easier to use CocoaPods.
+If you wish to use CocoaPods and haven't set it up yet, please instead refer to [that article](https://engineering.brigad.co/demystifying-react-native-modules-linking-ae6c017a6b4a).
+
+### Android:
+
+Android - react-native-webview version <6:
+This module does not require any extra step after running the link command 🎉
+
+Android - react-native-webview version >=6.X.X:
+Please make sure AndroidX is enabled in your project by editting `android/gradle.properties` and adding 2 lines:
+
+```
+android.useAndroidX=true
+android.enableJetifier=true
+```
+
+For Android manual installation, please refer to [this article](https://engineering.brigad.co/demystifying-react-native-modules-linking-964399ec731b) where you can find detailed step on how to link any react-native project.
+
+### Windows:
+
+Autolinking is supported for React Native Windows v0.63 and higher. If your app uses a React Native Windows version that does not have autolinking support, make the following additions to the given files manually:
+
+#### **windows/myapp.sln**
+
+Add the `ReactNativeWebView` project to your solution.
+
+1. Open the solution in Visual Studio 2019
+2. Right-click Solution icon in Solution Explorer > Add > Existing Project
+   Select `node_modules\react-native-webview\windows\ReactNativeWebView\ReactNativeWebView.vcxproj`
+
+#### **windows/myapp/myapp.vcxproj**
+
+Add a reference to `ReactNativeWebView` to your main application project. From Visual Studio 2019:
+
+1. Right-click main application project > Add > Reference...
+   Check `ReactNativeWebView` from Solution Projects.
+
+2. Modify files below to add the package providers to your main application project
+
+#### **pch.h**
+
+Add `#include "winrt/ReactNativeWebView.h"`.
+
+#### **app.cpp**
+
+Add `PackageProviders().Append(winrt::ReactNativeWebView::ReactPackageProvider());` before `InitializeComponent();`.
+
+Note if you want to enable scroll with Touch for the WebView component you must disable perspective for your app using [ReactRootView.IsPerspectiveEnabled](https://microsoft.github.io/react-native-windows/docs/ReactRootView#isperspectiveenabled).
+
+## 3. WebView2 Support
+The WebView2 control is a [WinUI](https://docs.microsoft.com/windows/apps/winui/) control that renders web content using the Microsoft Edge (Chromium) rendering engine. We have added support for the WebView2 control to the react-native-webview community module in v11.18.0.
+If your app is RNW v0.68 or higher, follow these steps:
+
+  i. Let autolinking handle adding the `ReactNativeWebView` project to your app.
+
+  ii. Customize your app's WinUI 2.x version to version 2.8.0-prerelease.210927001 or higher. See [here](https://microsoft.github.io/react-native-windows/docs/customizing-sdk-versions) for instructions. The WinUI 2.x support for WebView2 is not yet available in "stable" releases, so for now you will need to use a prerelease version.
+  
+  iii. You may need to specify the `Microsoft.Web.WebView2` package in your app's `packages.config` file. If this is needed, you will get a build error listing the version of the package that you needed to specify. Simply add the package to your `packages.config`, and you should be good to go.
+
+Now you can access the WinUI WebView2 control from your app's JavaScript via the `useWebView2` prop.
+
+## 4. Import the webview into your component
+
+```js
+import React, { Component } from 'react';
+import { WebView } from 'react-native-webview';
+
+class MyWeb extends Component {
+  render() {
+    return (
+      <WebView
+        source={{ uri: 'https://infinite.red' }}
+        style={{ marginTop: 20 }}
+      />
+    );
+  }
+}
+```
+
+Minimal example with inline HTML:
+
+```js
+import React, { Component } from 'react';
+import { WebView } from 'react-native-webview';
+
+class MyInlineWeb extends Component {
+  render() {
+    return (
+      <WebView
+        originWhitelist={['*']}
+        source={{ html: '<h1>Hello world</h1>' }}
+      />
+    );
+  }
+}
+```
+
+Next, check out the [API Reference](Reference.md) or [In-Depth Guide](Guide.md).
+
+## Translations
+
+This file is available at:
+
+- [Brazilian portuguese](Getting-Started.portuguese.md)