Skip to content

Commit baa5c39

Browse files
Steven0351Steven0351
authored
chore: Update readme to be in line with the other portals libraries (#29)
* chore: Update readme to be in line with the other portals libraries
1 parent 93186f9 commit baa5c39

File tree

1 file changed

+11
-159
lines changed

1 file changed

+11
-159
lines changed

‎README.md

+11-159
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,17 @@
33
<img src="https://user-images.githubusercontent.com/5769389/134952353-7d7b4145-3a80-4946-9b08-17b3a22c03a1.png" width="560" />
44
</div>
55
<div align="center">
6-
⚡️ A supercharged native Web View for iOS and Android ⚡️
6+
⚡️ A supercharged native Web View for React Native ⚡️
77
</div>
88
<br />
99
<p align="center">
10-
<a href="https://github.com/ionic-team/react-native-ionic-portals/actions?query=workflow%3ACI"><img src="https://img.shields.io/github/workflow/status/ionic-team/ionic-portals/CI?style=flat-square" /></a>
10+
<img src="https://img.shields.io/badge/platform-iOS%2013%2B-lightgrey?style=flat-square" alt="Supports iOS 13 and up" />
11+
<img src="https://img.shields.io/badge/platform-Android%20SDK%2021%2B-brightgreen?style=flat-square" alt="Supports Android SDK 21 and up" />
12+
<img src="https://img.shields.io/badge/platform-React%20Native%200.63.3%2B-blue?style=flat-square" alt="Supports React Native 0.63.3 and up" />
13+
</p>
14+
<p align="center">
15+
<a href="https://github.com/ionic-team/ionic-portals/actions?query=workflow%3ACI"><img src="https://img.shields.io/github/workflow/status/ionic-team/react-native-ionic-portals/Verify?style=flat-square" /></a>
1116
<a href="https://www.npmjs.com/package/@ionic/portals-react-native"><img src="https://img.shields.io/npm/l/@ionic/portals-react-native?style=flat-square" /></a>
12-
<a href="https://www.npmjs.com/package/@ionic/portals-react-native"><img src="https://img.shields.io/npm/v/@ionic/portals-react-native?style=flat-square" /></a>
1317
</p>
1418
<p align="center">
1519
<a href="https://ionic.io/docs/portals"><img src="https://img.shields.io/static/v1?label=docs&message=ionic.io/portals&color=blue&style=flat-square" /></a>
@@ -18,166 +22,15 @@
1822

1923
---
2024

21-
Ionic Portals is a supercharged native Web View component for iOS and Android that lets you add web-based experiences to React Native mobile apps. It enables React Native and web teams to better collaborate and bring new and existing web experiences to mobile in a safe, controlled way.
25+
Ionic Portals is a supercharged native Web View component for React Native that lets you add web-based experiences to native mobile apps. It enables native and web teams to better collaborate and bring new and existing web experiences to mobile in a safe, controlled way.
2226

2327
## Getting Started
2428

25-
### Installation
26-
`npm install @ionic/portals-react-native`
27-
or
28-
`yarn add @ionic/portals-react-native`
29-
30-
### Usage
31-
Register Portals with your [product key](#Registration):
32-
```javascript
33-
import { register } from '@ionic/portals-react-native';
34-
35-
register('YOUR_PORTAL_KEY_HERE');
36-
```
37-
38-
Create a Portal and add it to the portal registry:
39-
```javascript
40-
import { addPortal } from '@ionic/portals-react-native';
41-
const helloPortal = {
42-
// A unique name to reference later
43-
name: 'hello',
44-
// This is the location of your web bundle relative to the asset directory in Android and Bundle.main in iOS
45-
// This will default to the name of the portal
46-
startDir: 'portals/hello',
47-
// Any initial state to be provided to a Portal if needed
48-
initialContext: {
49-
greeting: 'Hello, world!'
50-
}
51-
};
52-
53-
addPortal(helloPortal);
54-
```
55-
56-
Create a PortalView in your view hierarchy:
57-
```javascript
58-
import { PortalView } from '@ionic/portals-react-native';
59-
60-
<PortalView
61-
// The name of the portal to be used in the view
62-
name='hello'
63-
64-
// Set any initial context you may want to override.
65-
initialContext={{ greeting: 'Goodbye!' }}
66-
67-
// Setting a size is required
68-
style={{ flex: 1, height: 300 }}
69-
/>
70-
```
71-
72-
#### iOS Specific Configuration
73-
##### AppDelegate
74-
Both Capacitor and React Native have classes named `AppDelegate`. To prevent a clash that can prevent your React Native application from launching,
75-
you will need to rename `AppDelegate` to something else:
76-
```objective-c
77-
// AppDelegate.h
78-
@interface RNAppDelegate : UIResponder <UIApplicationDelegate, RCTBridgeDelegate>
79-
```
80-
81-
```objective-c
82-
// AppDelegate.m
83-
@implementation RNAppDelegate
84-
@end
85-
```
86-
87-
```objective-c
88-
// main.m
89-
#import <UIKit/UIKit.h>
90-
91-
#import "AppDelegate.h"
92-
93-
int main(int argc, char *argv[])
94-
{
95-
@autoreleasepool {
96-
return UIApplicationMain(argc, argv, nil, NSStringFromClass([RNAppDelegate class]));
97-
}
98-
}
99-
```
100-
101-
##### Podfile
102-
There are two methods you may use to ensure Portals can integrate into your React Native application: a custom `pre_install` hook or adding `use_frameworks!` to your Podfile. Only one of these approaches is needed to ensure that Capacitor is compiled as a dynamic framework.
103-
104-
**pre_install**
105-
106-
Using the `pre_install` hook allows you to keep all the other React Native dependencies as static frameworks:
107-
```ruby
108-
# These frameworks are required to be dynamic.
109-
dynamic_frameworks = ['Capacitor', 'CapacitorCordova']
110-
111-
pre_install do |installer|
112-
installer.pod_targets.each do |pod|
113-
if dynamic_frameworks.include?(pod.name)
114-
def pod.static_framework?
115-
false
116-
end
117-
def pod.build_type
118-
Pod::BuildType.dynamic_framework
119-
end
120-
end
121-
end
122-
end
123-
```
124-
125-
**use_frameworks**
126-
127-
Alternative to the `pre_install` hook, you can add `use_frameworks!` to your Podfile application target. Using this approach requires removing `use_flipper!()` from the Podfile.
128-
129-
### Communicating between React Native and Web
130-
One of the key features of Ionic Portals for React Native is facilitating communication between the web and React Native layers of your application.
131-
Publishing a message to the web:
132-
```javascript
133-
import { publish } from '@ionic/portals-react-native';
134-
135-
publish('topic', { number: 1 })
136-
```
137-
138-
Subscribe to messages from the web:
139-
```javascript
140-
import { subscribe } from '@ionic/portals-react-native';
141-
142-
let subscriptionReference = await subscribe('topic', message => {
143-
// Here you have access to:
144-
// message.data - Any data sent from the web
145-
// message.subscriptionRef - The subscription reference used to manage the lifecycle of the subscription
146-
// message.topic - The topic the message was published on
147-
})
148-
```
149-
150-
When you no longer need to receive events, unsubscribe:
151-
```javascript
152-
import { unsubscribe } from '@ionic/portals-react-native';
153-
154-
unsubscribe('channel:topic', subscriptionReference)
155-
```
156-
157-
To see an example of Portals Pub/Sub in action that manages the lifecycle of a subscription with the lifecycle of a React Native component, refer to the [`PubSubLabel`](https://github.com/ionic-team/react-native-ionic-portals/blob/af19df0d66059d85ab8dde493504368c3bf39127/example/App.tsx#L53) implementation in the example project.
158-
159-
### Using Capacitor Plugins
160-
If you need to use any Capacitor plugins, the classpath of the Android plugins will have to be provided to the `Portal` `androidPlugins` property.
161-
162-
```javascript
163-
const helloPortal = {
164-
name: 'hello',
165-
startDir: 'portals/hello',
166-
androidPlugins: ['com.capacitorjs.plugins.camera.CameraPlugin'],
167-
initialContext: {
168-
greeting: 'Hello, world!'
169-
}
170-
};
171-
```
172-
173-
No configuration for iOS is needed since plugins are automatically registered when the Capacitor bridge initializes on iOS.
174-
175-
### Bundling Your Web Apps
176-
Currently there is no tooling for bundling your web apps directly as part of @ionic/portals-react-native. Please follow the [native guides](https://ionic.io/docs/portals/how-to/pull-in-web-bundle#setup-the-web-asset-directory) to manage this as part of the native build process.
29+
See our docs to [get started with Portals](https://ionic.io/docs/portals/getting-started/guide).
17730

17831
## Registration
17932

180-
Ionic Portals for React Native requires a key to use. Once you have integrated Portals into your project, login to your ionic account to get a key. See our doc on [how to register for free and get your Portals license key](https://ionic.io/docs/portals/how-to/get-a-product-key) and refer to the [usage](#Usage) section on how to add your key to your React Native application.
33+
The Ionic Portals library for React Native requires a **free** license key to use. Once you have integrated Portals into your project, login to your ionic account to get a key. See our doc on [how to register for free and get your Portals license key](https://ionic.io/docs/portals/how-to/get-a-product-key) and refer to the [React Native](https://ionic.io/docs/portals/getting-started/react-native) getting started guides to see where to add your key.
18134

18235
## FAQ
18336

@@ -191,7 +44,6 @@ See our [license](https://github.com/ionic-team/ionic-portals/blob/main/LICENSE.
19144

19245
### How is Portals Related to Capacitor and Ionic?
19346

194-
Ionic Portals is a solution that lets you add web-based experiences to your native mobile apps. Portals uses [Capacitor](https://capacitorjs.com) as a bridge between the native code and the web code to allow for cross-communication between the two layers. Because Portals uses Capacitor under the hood, you are able to use any existing [Capacitor Plugins](https://capacitorjs.com/docs/plugins) and even most [Cordova Plugins](https://capacitorjs.com/docs/plugins/cordova) while continuing to use your existing native workflow. Portals for React Native brings these capabilities to React Native applications.
47+
Ionic Portals is a solution that lets you add web-based experiences to your native mobile apps. Portals uses [Capacitor](https://capacitorjs.com) as a bridge between the native code and the web code to allow for cross-communication between the two layers. Because Portals uses Capacitor under the hood, you are able to use any existing [Capacitor Plugins](https://capacitorjs.com/docs/plugins) while continuing to use your existing native workflow.
19548

19649
[Ionic Framework](https://ionicframework.com/) is the open-source mobile app development framework that makes it easy to build top quality native and progressive web apps with web technologies. Your web experiences can be developed with Ionic, but it is not necessary to use Portals.
197-

0 commit comments

Comments
 (0)