Skip to content

Latest commit

 

History

History
62 lines (40 loc) · 5.27 KB

README.md

File metadata and controls

62 lines (40 loc) · 5.27 KB
Raw

iTwin Mobile SDK iOS Samples

Consistency Across Modules

These samples make use of the itwin-mobile-sdk-ios Swift Package (which itself uses the itwin-mobile-native-ios Swift Package), as well as the @itwin/mobile-sdk-core and @itwin/mobile-ui-react npm modules. In order to work properly, all of these packages have to be in sync with each other. When new functionality is added to any of the dependent modules, and that new functionality is used in the samples, the samples won't work until the next official release of the dependent modules. That means that there is a very good chance that the main branch will not work at any given time. To avoid problems when using these samples, you should always check out a release tag.

Client ID Setup

Before building the samples, you must configure a Client ID for yourself. To do so, follow the instructions here.

ITMApplication.xcconfig Setup

  1. Create a a file named ITMApplication.xcconfig in this directory with the following contents:

    ITMAPPLICATION_CLIENT_ID = <Your Client ID>
ITMAPPLICATION_SCOPE = <Your Scope>

    Notes:

    • Do not surround your values with quotes.

    • If you already had a Client ID, browse to your app's page in my-apps. If you just created it, you should already be there.

  2. Copy your client ID from the app's page, then replace <Your Client ID>.

  3. Use the "Copy" button in the Scopes section of the app's page to copy your scopes to the clipboard. Then replace <Your scope>. Finally, add offline_access to the end of the list of scopes (separated from the others with a space).

NPM Setup

Follow the npm setup instructions here.

Running the Samples

Once you have performed the above setup, you can build and run the samples.

Note: The samples must currently use Rosetta 2 mode when targeting the iOS Simulator on an Apple Silicon Mac, which requires Xcode 14.3 or later. (This will probably be fixed in the future.) The first time you run on the simulator, you will get a dialog saying the build failed due to a required architecture being missing. Select Build for Rosetta in that dialog. You will probably also have to set ITMAPPLICATION_DISABLE_AUTH = YES in ITMApplication.xcconfig in order to avoid having it crash during startup. That means that only local iModels can be loaded. You can drag and drop Snapshot iModels/Building Blocks.bim onto the running iOS Simulator to open the iTwin Mobile SDK sample model. If running the simulator from the command line instead of Xcode, the simctl launch command must be run using arch -arch x86_64 in order to cause it to use Rosetta 2 mode.

  1. Open the appropriate Xcode project or workspace.
  2. Xcode will take some time to download the Swift Packages that each sample depends on the first time you open that sample Xcode project. Also, it appears that Xcode sometimes randomly fails when installing Swift Packages. If this happens, select File->Packages->Reset Package Caches.
  3. Select the project in the Xcode navigator.
  4. Select the only entry under TARGETS.
  5. Select the Signing & Capabilities tab.
  6. Select your team from the Team popup menu.
  7. Use git diff to see the team ID value that was added to project.pbxproj after the above change, and then set the DEVELOPMENT_TEAM value in ITMApplication.xcconfig to contain that value. You can then revert the change to project.pbxproj.
  8. Run.
  9. If you get an error dialog that says Could not connect to React debug server., make sure that your React debug server is running (from the end of the npm setup instructions). If it is, the next thing to try is to uncomment the ITMAPPLICATION_USE_IP = YES line in iOSSamples.xcconfig.
  10. Once a sample is installed on your device, you can use Finder to copy a Snapshot iModel to the device if you want to open local snapshot models in the sample:
    1. Select your connected device in Finder's left navigation pane.
    2. Select the Files tab.
    3. Drag and drop .bim Snapshot iModel files into the "iTwin Starter" app or the "SwiftUIStarter" app.
  11. Please see Debugging.md for instructions on debugging.

Organization

The MobileStarter and SwiftUIStarter sample apps are both simple apps that present a full-screen web view. The app UI inside this web view is a React app in the cross-platform/react-app directory of this repository.

It is recommended that you use Visual Studio Code to edit your TypeScript code. Opening the react-app directory itself in Visual Studio code will generally be the most convenient way to do this. If you do this, you can use Cmd+Shift+B to start the React debug server, and omit using npm run start in a Terminal window.

The project.json file inside react-app contains dependencies for @itwin/mobile-sdk-core and @itwin/mobile-ui-react. It also contains dependencies for all the various iModelJS packages. These latter dependencies are optional (since they are already dependencies of @itwin/mobile-ui-react), but if they are omitted, Visual Studio Code will not autocomplete against those packages without first manually importing the desired class or function.