Apple

The following is a guide for building apps on Apple's MacOS and iOS operating systems.

Prerequisites

  1. Sign up for a (free) Apple Developer account.
  2. Register your devices for testing. You can use ssc list-devices command to get your Device ID (UDID). Device should be connected to your mac by wire.
  3. Create a wildcard App ID for the application you are developing.
  4. Write down your Team ID. It's in the top right corner of the website. You'll need this later.

MacOS

  • Xcode Command Line Tools. If you don't have them already, and you don't have xcode, you can run the command xcode-select --install.

iOS

Code Signing Certificates

  • Open Keychain Access application on your mac (it's in Applications/Utilities).
  • In the Keychain Access application choose Keychain Access -> Certificate Assistant -> Request a Certificate From a Certificate Authority...
  • Type you email in the User Email Address field. Other form elements are optional.
  • Choose Request is Saved to Disc and save your certificate request.

MacOS

Signing software on MacOS is optional but it's the best practice. Not signing software is like using http instead of https.

  • Create a new Developer ID Application certificate on the Apple Developers website.
  • Choose a certificate request you've created 2 steps earlier.
  • Download your certificate and double click to add it to your Keychain.

iOS

To run software on iOS, it must be signed by Xcode using the certificate data contained in a "Provisioning Profile". This is a file generated by Apple and it links app identity, certificates (used for code signing), app permissions, and phystical devices.

  • Create a new iOS Distribution (App Store and Ad Hoc) certificate on the Apple Developers website.
  • Choose a certificate request you've created 2 steps earlier.
  • Download your certificate and double click to add it to your Keychain.

When you run ssc compile --target=ios . on your project for the first time, you may see the following because you don't have a provisioning profile:

ssc compile --target=ios .
• provisioning profile not found: /Users/chicoxyzzy/dev/socketsupply/birp/./distribution.mobileprovision. Please specify a valid provisioning profile in the ios_provisioning_profile field in your `ssc.config`
  • Create a new Ad Hoc profile. Use the App ID you created with the wildcard.
  • Pick the certificate that you added to your Keychain two steps earlier.
  • Add the devices that the profile will use.
  • Add a name for your new distribution profile (we recommend to name it "distribution").
  • Download the profile and double click it. This action will open Xcode. You can close it after it's completely loaded.
  • Place your profile to your project directory (same directory as ssc.config). The profiles are secret, add your profile to .gitignore.

Configuration

MacOS

You will want to ensure the following fields are filled out in your ssc.config file. They will look something like this...

mac_team_id: Z3M838H537
mac_sign: Developer ID Application: Operator Tools Inc. (Z3M838H537)

iOS

  1. Set the apple_team_id value in ssc.config to the value of Team ID here
  2. Set the ios_distribution_method value in ssc.config to the ad-hoc
  3. Set the ios_codesign_identity value in ssc.config to the certificate name as it's displayed in the Keychan
  4. Set the ios_provisioning_profile value in ssc.config to the filename of your certificate (i.e., "distribution.mobileprovision").
  5. Set the ios_provisioning_specifier value in ssc.config to the profile name (as in the Profiles List)

Development

Create a simulator VM and launch the app in it

ssc compile --target=iossimulator -r .

Distribution And Deployment

ssc compile --target=ios -c -p -xd .

To your device

Install Apple Configurator, open it and install Automation Tools from the menu.

Connect your device and run ssc install-app <path> where path is the root directory of your application (the one where ssc.config is located).

Alternative way to install your app is to open the the Apple Configurator app and drag the inner /dist/build/[your app name].ipa/[your app name].ipa file onto your phone.

To the Apple App Store

xcrun altool --validate-app \
  -f file \
  -t platform \
  -u username [-p password] \
  [--output-format xml]
xcrun altool --upload-app \
  -f file \
  -t platform \
  -u username [-p password] \
  [—output-format xml]

Debugging

Check the [troubleshooting guide][/troubleshooting] first. You can also run lldb and attach to a process, for example...

process attach --name TestExample-dev

Logging

To see logs on either platform, open Console.app (installed on MacOS by default) and in the right side panel pick the device or computer name.

Working with the file system on iOS

iOS Application Sandboxing has a set of rules that limits access to the file system. Apps can only access files in their own sandboxed home directory.

Directory Description
Documents The app’s sandboxed documents directory. The contents of this directory is backed up by iTunes and may be set as accessable to the user via iTunes when UIFileSharingEnabled is set to true in application's info.plist.
Library The app’s sandboxed library directory. The contents of this directory are synchronised via iTunes (except the Library/Caches subdirectory, see below), but never exposed to the user.
Library/Caches The app’s sandboxed caches directory. The contents of this directory are not synchronised via iTunes, and may be deleted by the system at any time. It's a good place to store data which provides a good offline-first experience for the user.
Library/Preferences The app’s sandboxed preferences directory. The contents of this directory are synchronised via iTunes. It's purpose is to be used by the Settings app. Avoid creating your own files in this directory.
tmp The app’s sandboxed temporary directory. The contents of this directory are not synchronised via iTunes, and may be deleted by the system at any time. Although, it's recommended that you delete data which is not necessary anymore manually to minimize the space your app takes up on the file system. Use this directory to store data which is only useful during the app runtime.

Desktop Guide

Getting Started

Open a terminal, navigate to where you keep your code. Create a directory and initilaize it.

ssc init

Mobile Guide

Getting Started

Open a terminal, navigate to where you keep your code. Create a directory and initilaize it.

ssc init

This will create an ssc.config file as well as a src directory with an index.html file in it. First, open the config file in your editor and replace some of the example values with your own. Here's an example.

<!doctype html>
<html>
  <head>
    <script src="index.js"></script>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <meta http-equiv="Content-Security-Policy" content="connect-src child-src 'none';">
    <link rel="stylesheet" href="index.css">
  </head>
  <body>
    <h1>Hello, World</h1>
  </body>
</html>

Note! Don't use <script type="module"></script>, iOS doesn't support it.

Coding a UI

UI is written in HTML, JS and CSS. Of course you can bring whatever tools you want to the party. But let's start simple. The easiest way to see your UI is to build this as a desktop app and show a window that runs the code.

ssc init

Development Cycle

You'll probably want to write some code, see it, change it, and repeat this flow. The typical approach is to create a watch script that rebuilds your files when there are changes. If you provide a port, the ssc command will try to load http://localhost.

ssc compile -r --port=8000 .

You'll need to tell your build script the output location. The ssc command can tell you the platform specific build destination. For example.

./myscript `ssc list-build-target .`

Building for and launching the mobile simulator

After you get your UI looking how you want. The next step is to try it out on the simulator. At this point we can use either the -ios or -android flags as well as the -simulator flag. This will createa a platform specific bundle, create and boot a simulator VM and then run your app in simulator if -r flag is provided.

ssc compile --target=iossimulator -r .

Debugging on the simulator

You can use Safari to attach the Web Inspector to the Simulator. In the Safari menu, navigate Develop -> Simulator -> index.html. This will be the exact same inspector you get while developing desktop apps.

Next Steps

API Reference

The JavaScript APIs are the same on iOS and Android. To see which methods and properties are available, check out the Mobile API docs.

Production

For specifics about production builds and deploying to devices and app stores, see either the iOS or Android guides.

FAQ

What is a Modern Runtime for Web Apps?

Modern does not refer to how recently any component of the software was written. For example we use libuv which certainly isn't new. In fact, it's considered boring and stable. It's the approach that's modern.

The client-server model was more relevant when computers were fewer and less powerful. Now we are surrounded by billions of computers that can connect directly to each other, so servers are becoming less relevant no mater how fast they are.

How can a peer replace a server?

A peer should not be asked to handle the same kind of work-loads as a server. If you develop an app that monopolizes a user's device, they will be unhappy, regardless of what architecture you are using. Peers should handle smaller work-loads in shorter bursts.

With Peer To Peer networks, growth increases availability and compute capacity. Despite how many peers join your network, you should continue to design with the assumption that peers are unreliable and infrequently online.

Why not Electron?

Electron's binary size and memory footprint are far from acceptable for most developers. The bulk of the weight comes from the decision to build-in V8 and a custom distribution of node.js.

Why not Tauri?

Tauri is a project for people who want to write Rust. Socket SDK is for Web Developers who want to create connected apps with HTML, CSS and JavaScript.

Why not Rust?

Webview is C++, so are the platforms that it runs on. The memory safety offered by Rust is great but becomes irrelevant when it's just a thin wrapper around a world of C++. It is possible to write C++ that is as safe as Rust, it's just a hell of a lot harder.

Does Webview render consistently across platforms?

Historically it did not. Now it does.

Is it secure?

Yes. As much as anything else. Just NEVER try to build a browser. NEVER evaluate arbitrary code. ALWAYS use a strong CSP. ALWAYS sanitize any data that will be rendered in a UI.

Will you support a specific feature?

Possibly, create a PR and make an argument for why the feature is relevant to everyone who would use this project.