@nativescript-community/https
Nativescript plugin for https requests
[](#table-of-contents)
## Table of Contents
* [Installation](#installation)
* [A drop-in replacement for the [default http module](https://docs.nativescript.org/cookbook/http).](#a-drop-in-replacement-for-the-default-http-modulehttpsdocsnativescriptorgcookbookhttp)
* [Features](#features)
* [FAQ](#faq)
* [Installation](#installation-1)
* [Examples](#examples)
* [Hitting an API using `GET` method](#hitting-an-api-using-get-method)
* [Configuration](#configuration)
* [Installing your SSL certificate](#installing-your-ssl-certificate)
* [Enabling SSL pinning](#enabling-ssl-pinning)
* [Disabling SSL pinning](#disabling-ssl-pinning)
* [useLegacy](#uselegacy)
* [Cookie](#cookie)
* [Enabling Cache](#enabling-cache)
* [Multipart form data](#multipart-form-data)
* [Options](#options)
* [Webpack / bundling](#webpack--bundling)
* [`iOS` Troubleshooting](#ios-troubleshooting)
* [`Android` troubleshooting](#android-troubleshooting)
* [Thanks](#thanks)
* [Examples:](#examples-1)
* [Demos and Development](#demos-and-development)
* [Repo Setup](#repo-setup)
* [Build](#build)
* [Demos](#demos)
* [Contributing](#contributing)
* [Update repo ](#update-repo-)
* [Update readme ](#update-readme-)
* [Update doc ](#update-doc-)
* [Publish](#publish)
* [modifying submodules](#modifying-submodules)
* [Questions](#questions)
[](#installation)
## Installation
Run the following command from the root of your project:
`ns plugin add @nativescript-community/https`
Easily integrate the most reliable native networking libraries with the latest and greatest HTTPS security features.
> Android: version 4.x using okhttp 4.x changing minSDKVersion to 21! If lower needed stick to 3.x
> Plugin version 2.0.0 bumps `AFNetworking` on iOS to [4.0.0](https://github.com/AFNetworking/AFNetworking/releases/tag/4.0.0) which no longer relies on `UIWebView`. Make sure to run `pod repo update` to get the latest `AFNetworking` pod on your development machine.
#### A drop-in replacement for the [default http module](https://docs.nativescript.org/cookbook/http).
[](#features)
## Features
- Modern TLS & SSL security features
- Shared connection pooling reduces request latency
- Silently recovers from common connection problems
- Everything runs on a native background thread
- Transparent GZIP
- HTTP/2 support
- Multiform part
- Cache
- Basic Cookie support
[](#faq)
## FAQ
> What the flip is SSL pinning and all this security mumbo jumbo?
[How to make your apps more secure with SSL pinning](https://infinum.co/the-capsized-eight/how-to-make-your-ios-apps-more-secure-with-ssl-pinning).
> Do I have to use SSL pinning?
**No.** This plugin works out of the box without any security configurations needed. Either way you'll still benefit from all the features listed above.
[](#installation)
## Installation
```bash
tns plugin add @nativescript-community/https
```
[](#examples)
## Examples
### Hitting an API using `GET` method
```typescript
import * as Https from '@nativescript-community/https';
Https.request({
url: 'https://httpbin.org/get',
method: 'GET',
timeout: 30, // seconds (default 10)
})
.then(function (response) {
console.log('Https.request response', response);
})
.catch(function (error) {
console.error('Https.request error', error);
});
```
[](#configuration)
## Configuration
### Installing your SSL certificate
Create a folder called `assets` in your projects `app` folder like so `/app/assets`. Using chrome, go to the URL where the SSL certificate resides. View the details then drag and drop the certificate image into the `assets` folder.
#### Enabling SSL pinning
```typescript
import { knownFolders } from 'file-system';
import * as Https from '@nativescript-community/https';
let dir = knownFolders.currentApp().getFolder('assets');
let certificate = dir.getFile('httpbin.org.cer').path;
Https.enableSSLPinning({ host: 'httpbin.org', certificate });
```
Once you've enabled SSL pinning you **CAN NOT** re-enable with a different `host` or `certificate` file.
#### Disabling SSL pinning
```typescript
import * as Https from '@nativescript-community/https';
Https.disableSSLPinning();
```
All requests after calling this method will no longer utilize SSL pinning until it is re-enabled once again.
### useLegacy
There is a new option called `useLegacy`. You can set of every request options.
When using that option the request will behave more like {N} http module.
- the `content` returned by a request is not the resulting string but an object. It follows [HTTPContent](https://docs.nativescript.org/api-reference/interfaces/_http_.httpcontent) format for the most part. You can call `toJSON` or `toFile`. The only difference is that `toFile` returns a `Promise` which means that it is async and run in a background thread!
- an error return a `content` too allowing you to read its content.
### Cookie
By default basic Cookie support is enabled to work like in {N} `http` module.
In the future more options will be added
### Enabling Cache
```typescript
import { knownFolders, path } from '@nativescript/core/file-system';
import * as Https from '@nativescript-community/https';
Https.setCache({
diskLocation: path.join(knownFolders.documents().path, 'httpcache'),
diskSize: 10 * 1024 * 1024, // 10 MiB
});
/// later on when calling your request you can use the cachePolicy option
```
### Multipart form data
If you set the `Content-Type` header to `"multipart/form-data"` the request body will be evaluated as a multipart form data. Each body parameter is expected to be in this format:
```typescript
{
data: any
parameterName: string,
fileName?: string
contentType?: string
}
```
if `fileName` and `contentType` are set then data is expected to be either a `NSData` on iOS or a `native.Array` on Android.
### Options
```typescript
export interface HttpsSSLPinningOptions {
host: string;
certificate: string;
allowInvalidCertificates?: boolean;
validatesDomainName?: boolean;
commonName?: string;
}
import { HttpRequestOptions } from 'tns-core-modules/http';
export interface HttpsRequestOptions extends HTTPOptions {
useLegacy?: boolean;
cachePolicy?: 'noCache' | 'onlyCache' | 'ignoreCache';
onProgress?: (current: number, total: number) => void;
}
```
| SSLPinning Option | Description |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `host: string` | This must be the request domain name eg `sales.company.org`. |
| `commonName?: string` | Default: options.host, set if certificate CN is different from the host eg `*.company.org` (Android specific) |
| `certificate: string` | The uri path to your `.cer` certificate file. |
| `allowInvalidCertificates?: boolean` | Default: `false`. This should **always** be `false` if you are using SSL pinning. Set this to `true` if you're using a self-signed certificate. |
| `validatesDomainName?: boolean` | Default: `true`. Determines if the domain name should be validated with your pinned certificate. |
| Requests Option | Description |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `useLegacy?: boolean` | Default: `false`. [IOS only] set to true in order to get the response data (when status >= 300)in the `content` directly instead of `response.body.content`. |
| `cachePolicy?: 'noCache' | 'onlyCache' | 'ignoreCache'` | Set the cache policy to use with that request. This only works with GET requests for now. |
| `onProgress?: (current: number, total: number) => void` | [IOS only] Set the progress callback. |
[](#webpack--bundling)
## Webpack / bundling
Since you're probably shipping a certificate with your app (like [our demo does](https://github.com/nativescript-community/https/tree/master/demo/app/assets)),
make sure it's bundled by Webpack as well. You can do this by [adding the certificate(s) with the `CopyWebpackPlugin`](https://github.com/nativescript-community/https/blob/a5c841c0af7ff6d9994fa23f7fba0df0514c58f1/demo/webpack.config.js#L240).
[](#ios-troubleshooting)
## `iOS` Troubleshooting
> ### Please educate yourself on iOS's [App Transport Security](https://github.com/codepath/ios_guides/wiki/App-Transport-Security) before starting beef!
If you try and hit an `https` route without adding it to App Transport Security's whitelist it will not work!
You can bypass this behavior by adding the following to your projects `Info.plist`:
```xml
NSAppTransportSecurity
NSAllowsArbitraryLoads
```
> This plugin **does not** add `NSAllowsArbitraryLoads` to your projects `Info.plist` for you.
[](#android-troubleshooting)
## `Android` troubleshooting
If you app crashes with a message that it's doing too much networking on the main thread,
then pass the option `allowLargeResponse` with value `true` to the `request` function.
[](#thanks)
# Thanks
| Who | Why |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Robert Laverty](https://github.com/roblav96) | For creating and maintaining this plugin for a long time |
| [Jeff Whelple](https://github.com/gethuman) | For contributing |
| [Eddy Verbruggen](https://github.com/EddyVerbruggen) | For maintaining this before it got transferred |
| [AFNetworking](https://github.com/AFNetworking) | [AFNetworking](https://github.com/AFNetworking/AFNetworking) A delightful networking framework for iOS, OS X, watchOS, and tvOS. |
| [Square](http://square.github.io/) | [okhttp](https://github.com/square/okhttp) An HTTP+HTTP/2 client for Android and Java applications. |
### Examples:
- [Basic](demo-snippets/vue/Basic.vue)
- A basic example
[](#demos-and-development)
## Demos and Development
### Repo Setup
The repo uses submodules. If you did not clone with ` --recursive` then you need to call
```
git submodule update --init
```
The package manager used to install and link dependencies must be `pnpm` or `yarn`. `npm` wont work.
To develop and test:
if you use `yarn` then run `yarn`
if you use `pnpm` then run `pnpm i`
**Interactive Menu:**
To start the interactive menu, run `npm start` (or `yarn start` or `pnpm start`). This will list all of the commonly used scripts.
### Build
```bash
npm run build.all
```
WARNING: it seems `yarn build.all` wont always work (not finding binaries in `node_modules/.bin`) which is why the doc explicitly uses `npm run`
### Demos
```bash
npm run demo.[ng|react|svelte|vue].[ios|android]
npm run demo.svelte.ios # Example
```
Demo setup is a bit special in the sense that if you want to modify/add demos you dont work directly in `demo-[ng|react|svelte|vue]`
Instead you work in `demo-snippets/[ng|react|svelte|vue]`
You can start from the `install.ts` of each flavor to see how to register new demos
[](#contributing)
## Contributing
### Update repo
You can update the repo files quite easily
First update the submodules
```bash
npm run update
```
Then commit the changes
Then update common files
```bash
npm run sync
```
Then you can run `yarn|pnpm`, commit changed files if any
### Update readme
```bash
npm run readme
```
### Update doc
```bash
npm run doc
```
### Publish
The publishing is completely handled by `lerna` (you can add `-- --bump major` to force a major release)
Simply run
```shell
npm run publish
```
### modifying submodules
The repo uses https:// for submodules which means you won't be able to push directly into the submodules.
One easy solution is t modify `~/.gitconfig` and add
```
[url "ssh://git@github.com/"]
pushInsteadOf = https://github.com/
```
[](#questions)
## Questions
If you have any questions/issues/comments please feel free to create an issue or start a conversation in the [NativeScript Community Discord](https://nativescript.org/discord).