How your app is launched and how it starts the SDK
7 min read
An SDK app is started by the Onscryn agent, not by a person. Knowing exactly how it is started, and in what order your app should bring the SDK up and shut it down, removes most integration surprises.
The command line
When someone launches your app, the agent starts it in a Windows session of its own with a fixed set of arguments, followed by anything you entered in the app's Arguments field in the dashboard. The first argument after the executable is the instance id that ties your process to that one session.
| Position | Value | What it is for |
|---|---|---|
| 1 | Instance id | Identifies this one session. Pass it to Onscryn_Start as instanceId |
| 2 | Output folder | A working folder for this session. Pass it as outputDir. Frame files go here when you test with file dump |
| 3 | pipe | Tells your app to stream to Onscryn. Your own builds can accept anything else for local testing |
| 4 | Image quality | From the app's setting in the dashboard, 1 to 100. Pass it as tileQuality |
| 5 | Tile format | From the app's setting: webp, jpeg or raw. Map it to tileFormat 0, 1 or 2 |
| 6 and on | Your arguments | Whatever you typed in the app's Arguments field, passed through unchanged |
Start the SDK
Call Onscryn_Start once, after your main window exists. Pass the instance id from the command line, the transport, and the quality settings. Leave relayPipe empty to use the default pipe for the instance.
A zero-initialized options struct is a good start. Auto input and the auto UI tree are on unless you set their disable flags, so an app that does nothing else already gets working input and a UI tree.
| Field | What it does | Default |
|---|---|---|
| instanceId | The session's instance id, from the command line | Required |
| transport | 0 writes frames to files for local testing, 1 streams to Onscryn | 0 |
| outputDir | Where file-dump frames and logs go | None |
| relayPipe | A custom pipe name. Leave null to use the default for the instance | null |
| appInvisible | 1 means never show a window on any desktop | 0 |
| tileQuality | Image quality from 1 to 100 | 80 when unset by the app's setting |
| tileFormat | 0 for WebP, 1 for JPEG, 2 for raw BGRA | 0 |
| disableAutoInjectInput | 1 turns off automatic delivery of browser input, so you handle it | 0 (automatic input is on) |
| disableAutoUiTree | 1 turns off the automatic UI tree, so you send your own | 0 (automatic UI tree is on) |
Set callbacks
Call Onscryn_SetCallbacks with the events you care about. Any callback may be left null. They arrive on SDK threads, not on your UI thread, so hand work to the UI thread yourself if you touch controls. The callbacks are listed in the API reference.
In .NET, keep every delegate you pass in a field for the life of the process. A delegate that is only referenced locally can be garbage collected, and the next callback then crashes the app.
Register actions and printing
If you expose named actions, register them right after the callbacks. If you want browser printing, call Onscryn_EnablePrinting once. Both are optional, and both are covered in their own pages.
Shut down cleanly
The close callback tells your app that Onscryn wants it to close, for example when the session is ending. Close your main window in response. In your own shutdown path call Onscryn_Stop once, before the process exits.
If your app exits before it has presented a first frame, the session is marked failed with a message that the app exited before producing a first frame. That is the signal to check the DLL, the bitness and Onscryn_Start's return value.
Set DPI awareness first
Make your process per-monitor DPI aware before you create any window. The picture the browser scales then matches the pixels your app drew, and text stays sharp. In .NET call SetProcessDpiAwarenessContext with the per-monitor v2 context at the top of Main.