Skip to content

Handle Cross Border Alerts

Handle cross border alerts

This tutorial shows how to handle cross border alerts.

Get started

All cross border alerts are zone alerts representing a zone with administrative information change.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
void AlertObserver::onAlertInfoUpdated(const tn::drive::models::v1::AlertInfo& alertInfo)
{
    const auto& aheadAlerts = alertInfo.alerts_ahead;
    for (const auto& alert : aheadAlerts.cross_border_alerts)
    {
        // following type is cross border alert:
        // tn::drive::models::v1::AlertType::CrossBorder
        const auto type = alert.basic.type;

        // each alert item has a unique identifier, can be used to match alert updates
        const auto& id = alert.basic.id;

        if (alert.basic.distance_to_vehicle == 0)
        {
            // vehicle has entered the zone
            // get distance along road between zone begin location and current vehicle location
            const auto pastDistance = alert.zone.past_distance;
        }

        const auto& fromAdmin = alert.from_admin;
        const auto& toAdmin = alert.to_admin;

        // administrative level definition may be different from country to country
        // state level usually indicates the largest administrative unit in the country, e.g. state, province
        // city level usually indicates the a political and geographical subdivision of state, e.g. county, municipality
        // subcity level usually indicates the inner community inside a bigger city, e.g. district, locality
        // detailed information depends on the country
        if (fromAdmin.country_name.content != toAdmin.country_name.content)
        {
            // country changed
            // request an audio guidance prompt for it if it's close enough and never prompted before

            // record is a std::set<std::string> object to store the prompted alerts
            if (alert.basic.distance_to_vehicle < 500 && record.find(id) == record.end())
            {
                tn::drive::models::v1::AudioRequest request;
                request.request_type = tn::drive::models::v1::AudioPromptType::CountryBorderPrep;

                tn::drive::models::v1::AudioInstruction instruction;
                navigationService->requestAudio(request, instruction);
                playAudioInstruction(instruction);

                record.insert(id);
            }
        }
        else if (fromAdmin.state_name.content != toAdmin.state_name.content)
        {
            // state changed
        }
        else if (fromAdmin.city_name.content != toAdmin.city_name.content)
        {
            // city changed
        }
        else if (fromAdmin.subcity_name.content != toAdmin.subcity_name.content)
        {
            // subcity changed
        }

        showAlertIconOnMap(id, type, alert.zone.begin, alert.zone.end);
    }
}

Customize cross border detection level

Cross border detection level may be configured to adjust how ofter will it be notified. The default detection level is "subcity" which means all administrative changes will be notified.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const std::string crossBorderSettings = R"json(
{
    // Following configuration shows the default values for the cross border detection
    "AlertManager": 
    {
        //  CrossBorderMinLevel, value: {"Country", "State", "City", "SubCity"}.
        //  If this value is set to "SubCity", when sub city and levels above sub city changed,
        //  an alert will be notified.
        "CrossBorderMinLevel": "SubCity"
    }
}
)json";

const auto settings = tn::foundation::Settings::Builder()
    .setString(tn::drive::api::SettingConstants::SETTING_ALERT_JSON_CONTENT, crossBorderSettings)
    .build();

// enable alert component at the creation of a navigation service to make customized cross border detection settings effective
tn::drive::NavigationServiceOptions options;
options.enable_alert = true;

const auto navigationService = tn::drive::api::NavigationServiceFactory::createNavigationService(
    options, system, settings, mapContent, directionService);