You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Sources/HVCaptureSDK/HVCaptureSDK.docc/GettingStarted.md
+71-4Lines changed: 71 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -80,6 +80,72 @@ struct FooView: View {
80
80
81
81
Note that the SDK executes asynchronously, and the task that calls ``HVPartnerSDK/startCaptureSession(settings:info:)`` will suspend until the capture flow completes. As such, there's a very linear flow to interacting with the SDK, and once the call's `await` returns, the host app knows the SDK's capture session is complete (as seen with the `captureSessionCompleted` function above). If the capture session encountered a fatal error, it will raise the error as an exception.
82
82
83
+
### Starting an offline Capture & supplying the Job ID later
84
+
85
+
The host app can launch the SDK without supplying a remote job ID by following these steps:
86
+
1. Create a local job using ``HVPartnerSDK/createLocalJob(uuid:)``.
87
+
2. Start the capture session using the same local ID from before and setting ``JobIdentifier/jobID`` as well as the ``CaptureJobInformation/uploadSecret`` properties to `nil`.
88
+
89
+
Once the job ID becomes available use ``HVPartnerSDK/associateClientToRemoteJob(using:)`` to link the local job to its remote counterpart in order for uploads to start.
90
+
91
+
### Example:
92
+
93
+
```swift
94
+
importSwiftUI
95
+
96
+
structFooView: View {
97
+
// Create a local job
98
+
let jobIdentifier =try HVPartnerSDK.sharedInstance.createLocalJob()
99
+
// Or alternatively using a custom local ID
100
+
// let jobIdentifier = try HVPartnerSDK.sharedInstance.createLocalJob(uuid: localID)
Since we execute asynchronously within a Swift `Task`, we also honor its cancellation functionality and stop the capture session and capture flow UI if the task is cancelled.
Since the capture flow proceeds asynchronously, the host app may want to monitor the local job status as the capture proceeds. There are a few methods for obtaining Job status:
109
175
110
-
1. on-demand: The ``HVPartnerSDK`` class exposes a public method ``HVPartnerSDK/getClientJobStatus(for:)``. This is an `async` method that will return what the requested `Job`'s current status as a ``JobStatus``. If the requested ``Job`` doesn't exist locally, then it will raise a ``HVJobError`` exception.
176
+
1. on-demand: The ``HVPartnerSDK`` class exposes a public method ``HVPartnerSDK/getClientJobStatus(for:)``. This is an `async` method that will return what the requested `Job`'s current status as a ``JobStatus``. If the requested ``Job`` doesn't exist locally, then it will raise a ``HVJobError`` exception.
111
177
2. streaming: The ``HVPartnerSDK`` class also exposes a public method ``HVPartnerSDK/getJobStateObservable(for:)`` that returns a `Combine` publisher for the requested `Job`. The publisher will emit ``JobStatus`` instances whenever there's a change in the `Job`'s status. Additionally, `startCaptureSession` will return what the current `Job`'s status is when called, so together with `getJobStateObservable` you can track the whole status history for the `Job` (n.b. the initial state won't be published for a `Job`, so to get the complete status history you need to use the initial state returned from ``HVPartnerSDK/startCaptureSession(settings:info:)`` in conjunction with the publisher from `getJobStateObservable`). The initial Job state will generally be ``JobStatus.Created`` if newly created, or ``JobStatus.Draft`` if resuming an existing Job.
112
178
113
179
For example, adapting the previous example to monitor the `Job` status and build a complete `JobStatus` history for the capture session, you can do:
114
180
115
181
```swift
116
182
importCombine
117
-
importSwiftUI
118
183
importHVCaptureSDK
184
+
importSwiftUI
185
+
importCombine
119
186
120
187
structFooView: View {
121
188
let jobInfo: CaptureJobInformation
@@ -136,7 +203,7 @@ struct FooView: View {
136
203
// check if we have a listener for the job already, so we don't make duplicate listeners each time the view is created
137
204
if jobCancellables[jobInfo.identifier] ==nil {
138
205
let cancellable = HVPartnerSDK.sharedInstance.getJobStateObservable(for: jobInfo.identifier).sink(receiveValue: { (jobState: JobStatus) in
139
-
// NOTE: you can take various actions here based on the status change
206
+
// NOTE: you can t ake various actions here based on the status change
@@ -192,4 +259,4 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
192
259
193
260
> Warning: Since we use `BGTaskScheduler` for our background processing, we need to call ``HVPartnerSDK/registerForBackgroundJobs()`` **before** the application finishes launching. If not, then the application will raise an `NSInternalInconsistencyException` exception with the reason: `'All launch handlers must be registered before application finishes launching'`. This is a constraint imposed by the [BGTaskScheduler framework itself](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler/register(fortaskwithidentifier:using:launchhandler:)#Discussion) and if ignored will likely crash the application.
194
261
195
-
While using `registerForBackgroundJobs` enables the SDK to schedule background tasks on its own as needed, it's also possible to disable automatic background task scheduling and have more manual control over background task scheduling. This can be useful for applications that want closer control over background tasks spawned from the SDK and which already have their own background task scheduling. This can be achieved by **not** calling ``HVPartnerSDK/registerForBackgroundJobs()``, and instead calling ``HVPartnerSDK/initializeForBackground(parameters:)`` from within a [BGProcessingTask](https://developer.apple.com/documentation/backgroundtasks/bgprocessingtask). Under the hood, this will check if there are pending uploads. If there are no pending uploads, then it will exit and do nothing. If there are, then it'll run asynchronously and attempt to complete the pending uploads, performing a single upload at a time and exiting once the pending upload queue has been completed.
262
+
While using `registerForBackgroundJobs` enables the SDK to schedule background tasks on its own as needed, it's also possible to disable automatic background task scheduling and have more manual control over background task scheduling. This can be useful for applications that want closer control over background tasks spawned from the SDK and which already have their own background task scheduling. This can be achieved by **not** calling ``HVPartnerSDK/registerForBackgroundJobs()``, and instead calling ``HVPartnerSDK/initializeForBackground(parameters:)`` from within a [BGProcessingTask](https://developer.apple.com/documentation/backgroundtasks/bgprocessingtask). Under the hood, this will check if there are pending uploads. If there are no pending uploads, then it will exit and do nothing. If there are, then it'll run asynchronously and attempt to complete the pending uploads, performing a single upload at a time and exiting once the pending upload queue has been completed.
0 commit comments