diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea250033..872f8d3b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ Platform specific build instructions: - [Windows/clang](build-cmake-clang.cmd) - [Mac](docs/cpp-start-macosx.md) - [Linux](docs/cpp-start-linux.md). [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) or [Docker](https://www.docker.com/products/docker-desktop) can be used to build for various Linux distros. Please refer to [build-docker.cmd](build-docker.cmd) script and [the list of supported containers](docker/). Docker build script accepts the container name as first argument. -- [iOS/iPadOS](build-ios.sh) +- [iOS/iPadOS](docs/cpp-start-ios.md) - [Android](docs/cpp-start-android.md) Other resources to learn how to setup the build system: diff --git a/README.md b/README.md index 3536d046..8340e57d 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,8 @@ To build the SDK, please refer to [How to build the SDK](CONTRIBUTING.md#How_to_ | Target Platform | Supported | Covered by CI | | ------------------------------ | ------------------ | ------------------ | | Android | partial† | | + | iOS 10+ (simulator) | :white_check_mark: | :white_check_mark: | + | iOS 10+ (arm64, arm64e) | :white_check_mark: | | | Linux (x86, x64, arm, aarch64) | :white_check_mark: | | | Mac OS X 10.11+ | :white_check_mark: | | | Mac OS X (latest) | :white_check_mark: | :white_check_mark: | diff --git a/docs/cpp-start-ios.md b/docs/cpp-start-ios.md new file mode 100644 index 00000000..036d4dd5 --- /dev/null +++ b/docs/cpp-start-ios.md @@ -0,0 +1,60 @@ + +This tutorial guides you through the process of integrating the 1DS SDK into your existing C++ iOS app. + +## 1. Clone the repository + +Run `git clone https://github.com/microsoft/cpp_client_telemetry.git` to clone the repo. If your project requires any of the private modules (ECS, DefaultDataViewer, etc.), you need to add `--recurse-submodules` when cloning to tell git to add `lib/modules` repo. You will be prompted to enter your credentials to clone. Use your MSFT GitHub username and GitHub token. + +## 2. Build all + +### Simulator + +Run `build-ios.sh [clean] [release|debug]` script in the root folder of the source tree. This will fetch the necessary build tools and build the SDK. You will be prompted to enter your root password in order to install the necessary build tools and the resulting SDK package. + +### Device + +Run `build-ios.sh [clean] [release|debug] [arm64|arm64e]`. + +## 3. Integrate the SDK into your C++ project + +SDK package contains headers and library installed at the following locations: + +* Headers: /usr/local/include/mat +* Library: /usr/local/lib/${arch}/libmat.a + +1DS SDK is built using cmake, but you can explore building it with any other build system of your choice. + + +## 4. Instrument your code to send a telemetry event + +1. Include the main 1DS SDK header file in your main.cpp by adding the following statement to the top of your app's implementation file. + + ``` + #include "LogManager.hpp" + ``` + +2. Use namespace by adding the following statement after your include statements at the top of your app's implementation file. + + ``` + using namespace Microsoft::Applications::Events; + ``` + +3. Create the default LogManager instance for your project using the following macro in your main file: + + ``` + LOGMANAGER_INSTANCE + ``` + +4. Initialize the SDK, create and send a telemetry event, and then flush the event queue and shut down the telemetry +logging system by adding the following statements to your main() function. + + ``` + ILogger* logger = LogManager::Initialize("0123456789abcdef0123456789abcdef-01234567-0123-0123-0123-0123456789ab-0123"); + logger->LogEvent("My Telemetry Event"); + ... + LogManager::FlushAndTeardown(); + ``` + +You're done! You can now compile and run your app, and it will send a telemetry event using your ingestion key to your tenant. + +Please refer to [EventSender](https://github.com/microsoft/cpp_client_telemetry/tree/master/examples/cpp/EventSender) sample for more details. Other sample apps can be found [here](https://github.com/microsoft/cpp_client_telemetry/tree/master/examples/cpp/). All of our SDK samples require CMake build system, but you may consume the SDK using any other alternate build system of your choice (GNU Make, gn, etc.).