SDL supports two types of alerts: a large popup alert that typically takes over the whole screen and a smaller subtle alert that only covers a small part of screen.
Your SDL app may be restricted to only being allowed to send an alert when your app is open (i.e. the hmiLevel
is non-NONE
) or when it is the currently active app (i.e. the hmiLevel
is FULL
). Subtle alert is a new feature (RPC v7.0+) and may not be supported on all modules.
Copied to clipboard!
BOOL isAlertAllowed = [self.sdlManager.permissionManager isRPCNameAllowed:SDLRPCFunctionNameAlert]; BOOL isSubtleAlertAllowed = [self.sdlManager.permissionManager isRPCNameAllowed:SDLRPCFunctionNameSubtleAlert];
Copied to clipboard!
let isAlertAllowed = sdlManager.permissionManager.isRPCNameAllowed(.alert) let isSubtleAlertAllowed = sdlManager.permissionManager.isRPCNameAllowed(.subtleAlert)
An alert is a large pop-up window showing a short message with optional buttons. When an alert is activated, it will abort any SDL operation that is in-progress, except the already-in-progress alert. If an alert is issued while another alert is still in progress the newest alert will wait until the current alert has finished.
Depending on the platform, an alert can have up to three lines of text, a progress indicator (e.g. a spinning wheel or hourglass), and up to four soft buttons.
If no soft buttons are added to an alert some modules may add a default "cancel" or "close" button.
Use the SDLAlertView
to set all the properties of the alert you want to present.
An SDLAlertView
must contain at least either text
, secondaryText
or audio
for the alert to be presented.
Copied to clipboard!
SDLAlertView *alertView = [[SDLAlertView alloc] initWithText:<#(nullable NSString *)#> secondaryText:<#(nullable NSString *)#> tertiaryText:<#(nullable NSString *)#> timeout:<#(nullable NSNumber<SDLFloat> *)#> showWaitIndicator:<#(nullable NSNumber<SDLBool> *)#> audioIndication:<#(nullable SDLAlertAudioData *)#> buttons:<#(nullable NSArray<SDLSoftButtonObject *> *)#> icon:<#(nullable SDLArtwork *)#>];
Copied to clipboard!
let alertView = SDLAlertView(text: <#String?#>, secondaryText: <#String?#>, tertiaryText: <#String?#>, timeout: <#NSNumber?#>, showWaitIndicator: <#NSNumber?#>, audioIndication: <#SDLAlertAudioData?#>, buttons: <#[SDLSoftButtonObject]?#>, icon: <#SDLArtwork?#>)
Copied to clipboard!
alertView.softButtons = <#[SDLSoftButtonObject]?#>;
Copied to clipboard!
alertView.softButtons = <#[SDLSoftButtonObject]?#>
An alert can include a custom or static (built-in) image that will be displayed within the alert.
Copied to clipboard!
alertView.icon = <#(nullable SDLArtwork *)#>;
Copied to clipboard!
alertView.icon = <#SDLArtwork?#>
An optional timeout can be added that will dismiss the alert when the duration is over. Typical timeouts are between 3 and 10 seconds. If omitted, a default of 5 seconds is used.
Copied to clipboard!
alertView.timeout = 5;
Copied to clipboard!
alertView.timeout = 5
Not all modules support a progress indicator. If supported, the alert will show an animation that indicates that the user must wait (e.g. a spinning wheel or hourglass, etc). If omitted, no progress indicator will be shown.
Copied to clipboard!
alertView.showWaitIndicator = YES;
Copied to clipboard!
alertView.showWaitIndicator = true
An alert can also speak a prompt or play a sound file when the alert appears on the screen. This is done by creating an SDLAlertAudioData
object and setting it in the SDLAlertView
On Manticore, using alerts with audio (Text-To-Speech or Tones) work best in Google Chrome, Mozilla Firefox, or Microsoft Edge. Alerts with audio does not work in Apple Safari at this time.
Copied to clipboard!
SDLAlertAudioData *alertAudioData = [[SDLAlertAudioData alloc] initWithSpeechSynthesizerString:<#(nonnull NSString *)#>]; alertView.audio = alertAudioData;
Copied to clipboard!
let alertAudioData = SDLAlertAudioData(speechSynthesizerString: <#String#>) alertView.audio = alertAudioData
SDLAlertAudioData
can also play an audio file.
Copied to clipboard!
SDLAlertAudioData *alertAudioData = [[SDLAlertAudioData alloc] initWithAudioFile:<#(nonnull SDLFile *)#>]; alertView.audio = alertAudioData;
Copied to clipboard!
let alertAudioData = SDLAlertAudioData(audioFile: <#SDLFile#>) alertView.audio = alertAudioData
You can also play a combination of audio files and text-to-speech strings. The audio will be played in the order you add them to the SDLAlertAudioData
object.
Copied to clipboard!
SDLAlertAudioData *alertAudioData = [[SDLAlertAudioData alloc] initWithAudioFile:<#(nonnull SDLFile *)#>]; [alertAudioData addSpeechSynthesizerStrings:<#(nonnull NSArray<NSString *> *)#>];
Copied to clipboard!
let alertAudioData = SDLAlertAudioData(audioFile: <#SDLFile#>) alertAudioData.addSpeechSynthesizerStrings(<#[String]#>)
To play a notification sound when the alert appears, set playTone
to true
.
Copied to clipboard!
SDLAlertAudioData *alertAudioData = [[SDLAlertAudioData alloc] initWithSpeechSynthesizerString:<#(nonnull NSString *)#>]; alertAudioData.playTone = YES;
Copied to clipboard!
let alertAudioData = SDLAlertAudioData(speechSynthesizerString: <#String#>) alertAudioData.playTone = true
Copied to clipboard!
[sdlManager.screenManager presentAlert:alertView withCompletionHandler:^(NSError * _Nullable error) { if (error != nil) { // Something went wrong return; } // Alert was presented successfully }];
Copied to clipboard!
sdlManager.screenManager.presentAlert(alertView) { error in if let error = error { // Something went wrong return } // Alert was presented successfully }
You can cancel an alert that has not yet been sent to the head unit.
On systems with RPC v6.0+ you can dismiss a displayed alert before the timeout has elapsed. This feature is useful if you want to show users a loading screen while performing a task, such as searching for a list for nearby coffee shops. As soon as you have the search results, you can cancel the alert and show the results.
If connected to older head units that do not support this feature, the cancel request will be ignored, and the alert will persist on the screen until the timeout has elapsed or the user dismisses the alert by selecting a button.
Canceling the alert will only dismiss the displayed alert. If the alert has audio, the speech will play in its entirety even when the displayed alert has been dismissed. If you know you will cancel an alert, consider setting a short audio message like "searching" instead of "searching for coffee shops, please wait."
Copied to clipboard!
[alertView cancel];
Copied to clipboard!
alertView.cancel()
You can also use RPCs to present alerts. You need to use the Alert
RPC to do so. Note that if you do so, you must avoid using soft button ids 0 - 10000 and cancel ids 0 - 10000 because these ranges are used by the ScreenManager
.
A subtle alert is a notification style alert window showing a short message with optional buttons. When a subtle alert is activated, it will not abort other SDL operations that are in-progress like the larger pop-up alert does. If a subtle alert is issued while another subtle alert is still in progress the newest subtle alert will simply be ignored.
Touching anywhere on the screen when a subtle alert is showing will dismiss the alert. If the SDL app presenting the alert is not currently the active app, touching inside the subtle alert will open the app.
Depending on the platform, a subtle alert can have up to two lines of text and up to two soft buttons.
Because SubtleAlert
is not currently supported in the ScreenManager
, you need to be careful when setting soft buttons or cancel ids to ensure that they do not conflict with those used by the ScreenManager
. The ScreenManager
takes soft button ids 0 - 10000 and cancel ids 0 - 10000. Ensure that if you use custom RPCs that the soft button ids and cancel ids are outside of this range.
The following steps show you how to add text, images, buttons, and sound to your subtle alert. Please note that at least one line of text or the "text-to-speech" chunks must be set in order for your subtle alert to work.
Copied to clipboard!
SDLSubtleAlert *subtleAlert = [[SDLSubtleAlert alloc] initWithAlertText1:<#(nullable NSString *)#> alertText2:<#(nullable NSString *)#> alertIcon:<#(nullable SDLImage *)#> ttsChunks:<#(nullable NSArray<SDLTTSChunk *> *)#> duration:<#(nullable NSNumber<SDLUInt> *)#> softButtons:<#(nullable NSArray<SDLSoftButton *> *)#> cancelID:<#(nullable NSNumber<SDLInt> *)#>];
Copied to clipboard!
let subtleAlert = SDLSubtleAlert(alertText1: <#String?#>, alertText2: <#String?#>, alertIcon: <#SDLImage?#>, ttsChunks: <#[SDLTTSChunk]?#>, duration: <#(NSNumber & SDLUInt)?#>, softButtons: <#[SDLSoftButton]?#>, cancelID: <#(NSNumber & SDLInt)?#>)
Copied to clipboard!
// Remember that the ids must be > 10000 SDLSoftButton *button1 = [[SDLSoftButton alloc] initWithType:<#(nonnull SDLSoftButtonType)#> text:<#(nullable NSString *)#> image:<#(nullable SDLImage *)#> highlighted:<#(BOOL)#> buttonId:<#(UInt16)#> systemAction:<#(nullable SDLSystemAction)#> handler:^(SDLOnButtonPress * _Nullable buttonPress, SDLOnButtonEvent * _Nullable buttonEvent) { if (buttonPress == nil) { return; } <#Button has been pressed#> }]; subtleAlert.softButtons = @[button1];
Copied to clipboard!
// Remember that the ids must be > 10000 let button1 = SDLSoftButton(type: <#SDLSoftButtonType#>, text: <#String?#>, image: <#SDLImage?#>, highlighted: <#Bool#>, buttonId: <#UInt16#>, systemAction: <#SDLSystemAction?#>) { (buttonPress, buttonEvent) in guard buttonPress != nil else { return } <#Button has been pressed#> } subtleAlert.softButtons = [button1]
A subtle alert can include a custom or static (built-in) image that will be displayed within the subtle alert. Before you add the image to the subtle alert, make sure the image is uploaded to the head unit using the SDLFileManager
. Once the image is uploaded, you can show the alert with the icon.
Copied to clipboard!
subtleAlert.alertIcon = [[SDLImage alloc] initWithName:<#(nonnull NSString *)#> isTemplate:<#(BOOL)#>];
Copied to clipboard!
subtleAlert.alertIcon = SDLImage(name: <#String#>, isTemplate: <#Bool#>)
An optional timeout can be added that will dismiss the subtle alert when the duration is over. Typical timeouts are between 3 and 10 seconds. If omitted, a default of 5 seconds is used.
Copied to clipboard!
// Duration timeout is in milliseconds subtleAlert.duration = @4000;
Copied to clipboard!
// Duration timeout is in milliseconds subtleAlert.duration = NSNumber(4000)
A subtle alert can also speak a prompt or play a sound file when the subtle alert appears on the screen. This is done by setting the ttsChunks
parameter.
Copied to clipboard!
subtleAlert.ttsChunks = [SDLTTSChunk textChunksFromString:<#(nonnull NSString *)#>];
Copied to clipboard!
subtleAlert.ttsChunks = SDLTTSChunk.textChunks(from: <#String#>)
The ttsChunks
parameter can also take a file to play/speak. For more information on how to upload the file please refer to the Playing Audio Indications guide.
Copied to clipboard!
subtleAlert.ttsChunks = [SDLTTSChunk fileChunksWithName:<#(nonnull NSString *)#>];
Copied to clipboard!
subtleAlert.ttsChunks = SDLTTSChunk.fileChunks(withName: <#String#>)
Copied to clipboard!
[self.sdlManager sendRequest:subtleAlert withResponseHandler:^(SDLRPCRequest *request, SDLRPCResponse *response, NSError *error) { if (!response.success.boolValue) { <#Print out the error if there is one#> return; } <#Subtle alert was shown successfully#> }];
Copied to clipboard!
sdlManager.send(request: subtleAlert) { (request, response, error) in guard response?.success.boolValue == true else { <#Print out the error if there is one#> return } <#Subtle alert was shown successfully#> }
If desired, you can be notified when the user tapped on the subtle alert by registering for the SDLOnSubtleAlertPressed
notification.
Copied to clipboard!
[self.sdlManager subscribeToRPC:SDLDidReceiveSubtleAlertPressedNotification withObserver:self selector:@selector(subtleAlertPressed)]; - (void)subtleAlertPressed { <#The subtle alert was pressed#> }
Copied to clipboard!
sdlManager.subscribe(to: .SDLDidReceiveSubtleAlertPressed, observer: self, selector: #selector(subtleAlertPressed)) @objc func subtleAlertPressed() { <#The subtle alert was pressed#> }
You can dismiss a displayed subtle alert before the timeout has elapsed.
Canceling the subtle alert will only dismiss the displayed alert. If you have set the ttsChunk
property, the speech will play in its entirety even when the displayed subtle alert has been dismissed. If you know you will cancel a subtle alert, consider setting a short ttsChunk
.
There are two ways to dismiss a subtle alert. The first way is to dismiss a specific subtle alert using a unique cancelID
assigned to the subtle alert. The second way is to dismiss whichever subtle alert is currently on-screen.
Copied to clipboard!
// `cancelID` is the ID that you assigned when creating and sending the subtle alert SDLCancelInteraction *cancelInteraction = [[SDLCancelInteraction alloc] initWithSubtleAlertCancelID:cancelID]; [self.sdlManager sendRequest:cancelInteraction withResponseHandler:^(__kindof SDLRPCRequest * _Nullable request, __kindof SDLRPCResponse * _Nullable response, NSError * _Nullable error) { if (!response.success.boolValue) { <#Print out the error if there is one#> return; } <#The subtle alert was canceled successfully#> }];
Copied to clipboard!
// `cancelID` is the ID that you assigned when creating and sending the subtle alert let cancelInteraction = SDLCancelInteraction(subtleAlertCancelID: cancelID) sdlManager.send(request: cancelInteraction) { (request, response, error) in guard response?.success.boolValue == true else { <#Print out the error if there is one#> return } <#The subtle alert was canceled successfully#> }
Copied to clipboard!
SDLCancelInteraction *cancelInteraction = [SDLCancelInteraction subtleAlert]; [self.sdlManager sendRequest:cancelInteraction withResponseHandler:^(__kindof SDLRPCRequest * _Nullable request, __kindof SDLRPCResponse * _Nullable response, NSError * _Nullable error) { if (!response.success.boolValue) { <#Print out the error if there is one#> return; } <#The subtle alert was canceled successfully#> }];
Copied to clipboard!
let cancelInteraction = SDLCancelInteraction.subtleAlert() sdlManager.send(request: cancelInteraction) { (request, response, error) in guard response?.success.boolValue == true else { <#Print out the error if there is one#> return } <#The subtle alert was canceled successfully#> }