Alert Service

Notice: using alert service directly is a legacy way to leverage the ability of the TA SDK. It's recommended to use drive session instead. Refer to the guide of drive session for more information.

Overview

Alert service provides all the alert data, route situation and specific traffic information. The maximum length limitation the alert can detect is 5 km on a normal road and 80 km on a highway. The alert data source comes from the map and traffic supplier.

Key Concepts

Alert Type

Zone alert: presents an area with a warning. It's basically a composite with a sequence of links. The following table contains the supported zone alerts and corresponding type definitions in alert service.

Category	Types
School Zone	kSchoolZone
Conditional Speed Limit Zone Alert	kRainyDaySpeedLimit kSnowyDaySpeedLimit kTimeSpeedLimit kSeasonalTimeSpeedLimit kLaneSpeedLimit kFoggyDaySpeedLimit
Section Speed Camera	kSectionSpeedCamera
Access Restriction	kAccessRestriction
Physical Restriction	kPhysicalRestriction
Time Restriction	kTimedRestriction
Road Work	kRoadWork

Generic alert: presents a single point-based warning. It is usually a real-world object, such as a traffic sign or a safety camera. The following table contains the supported generic alerts and corresponding type definitions in alert service.

Category	Types
Camera	kSpeedCamera kRedlightCamera kBuslaneCamera kRedlightandspeedCamera kSectionstartCamera kSectionendCamera kDistanceCamera kNolrturnsCamera kOtherCamera kBeginingpointoflaneandspeedingviolationblockCamera kExclusivebuslaneandspeedingviolationCamera kExclusivebuslaneviolationCamera kInformationgatheringCamera kLoadingviolationCamera kNopassingenforcementCamera kOtherviolationCamera kOverloadingviolationCamera kParkingviolationCamera kShoulderlaneenforcementCamera
Traffic signs	kBeginOvertaking kEndOvertaking kProtectedOvertakingExtraLane kProtectedOvertakingExtraRight kProtectedOvertakingExtraLeft kLaneMergeRight kLaneMergeLeft kLaneMergeCenter kRailwayCrossingProtected kRailwayCrossingUnprotected kRoadNarrows kSharpCurveLeft kSharpCurveRight kWindingRoadStartingLeft kWindingRoadStartingRight kBeginOvertakingTrucks kEndOvertakingTrucks kSteepHillUpwards kSteepHillDownwards kStopSign kLateralWind kGeneralWarningSign(kQuickTurn) kRiskOfGrounding kGeneralCurve kEndOfAllRestrictions kGeneralHill kAnimalCrossing kIcyConditions kSlipperyRoad kFallingRocks kLeftFallingRocks kRightFallingRocks kSchoolSign kTramwayCrossing kCongestionHazard kAccidentHazard kPriorityOverOncomingTraffic kYieldToOncomingTraffic kCrossingWithPriorityFromRight kPedestrianCrossing kYield kBeginNoEngineBrake kEndNoEngineBrake kNoIdling kTruckRollOver kBeginLowGear kEndLowGear kBicycleCrossing kYieldToBicycles kUrbanArea kEmbankment kTwoWayTraffic kUnevenRoad kFloodArea kHumpBridge kSTurns kWindingRoad kMaxSpeed
TollBooth	kTollbooth
Other	kBlackSpot kFerry kTunnel kOverpass/kUnderpass(only korea) kUnpaved kSpeedBumper kCrossBorder

TollBooth information

Attribute	Description
name	The tollbooth name string

Traffic incident alert: presents a traffic incident with TMC-based traffic incident code. The following table contains the supported traffic incident type definitions in alert service.

Types	Description
kPoliceCheckPoint	The police check point
kAccident	Accident alert, it indicates that there exists a traffic accident
kAccidentCleared	Accident cleared alert, it indicates that an accident is cleared
kRoadConstruction	Road construction alert, it indicates that there exists roadworks incident ahead
kRoadConstructionEnded	Road construction ended alert, it indicates that a roadwork incident is cleared
kBlockedRoad	Blocked road alert, it indicates that there exists blocked roads ahead
kHazardousRoad	Hazardous road alert, it indicates there exists hazardous roads ahead
kHazardousRoadPassed	Hazardous road passed alert, it indicates there exists a hazardous roads cleared incident ahead
kLaneRestriction	Lane restriction alert, it indicates there exists lane restriction roads ahead
kLaneRestrictionOver	Lane restriction alert, it indicates that a lane restriction is over
kCongestion	Congestion alert, it indicates that there exists a congestion incident ahead
kCongestionCleared	Congestion alert, it indicates that there exists a congestion cleared incident ahead
kEntryBlock	Congestion alert, it indicates that there exists an entry block incident ahead
kEntryReopen	Congestion alert, it indicates that there exists an entry reopen incident ahead
kExitBlock	Congestion alert, it indicates that there exists an exit block incident ahead
kExitReopen	Congestion alert, it indicates that there exists an exit reopen cleared incident ahead
kTrafficFlow	Traffic flow alert, it indicates that there exists roads with traffic flow ahead

Highway information: presents the exit along the highway, including those ahead and behind the vehicle. Each highway information item contains the following contents:

Attribute	Description
Location	Get the location of this item on the highway. For highway exit, it means the position of exit branching off.
HighwayName	The link's name
ShieldInfo	The highway shield info
DistanceToVehicle	The distance from the item to vehicle
Exit	The exit property of highway info

The highway info details:

User position information: presents the road and administrative information nearby.

Attribute	Description
ClosestStreetInfo	The closest street info when vehicle is not on road
CurrentStreetName	The current street name
NextIntersection	The next intersection info
PreviousIntersection	The previous intersection info
AdminInfo	The current admin info
TimeZone	The current time zone info

ClosestStreetInfo: This attribute is only available when the vehicle is not on the road.

Attribute	Description
name	The street name
distanceToVehicle	The distance from current road to the street

Intersection Info

Attribute	Description
location	The location of this intersection
crossRoadInfos	All the cross road info at this intersection
currentRoadInfo	The current road info
distanceToVehicle	The distance between current vehicle postion and the intersection

Admin Info

Attribute	Description
countryCode	The country code
country	The country admin info
state	The state admin info
city	The city admin info
subcity	The subcity admin info

Admin Item

Attribute	Description
name	The admin's name
adminLevel	The admin level info such as country, state, city, etc

Time Zone

Attribute	Description
UTC_offset	UTC time offset based on UTC±00:00 in seconds
DST_offset	Daylight saving time in seconds
country_code	The country code
timezone_name	String representation of time zone name

Generic and zone alert information

Setup an alert service with alert detection enabled.

// system instance is created for sharing in the whole SDK
// settings instance should be created if any default setting does not meet the requirements, could be nullptr if default values are good enough
// mapContent instance is created for sharing in the whole SDK
// positionEngine instance is created for sharing in drive session services
auto service = tn::alert::AlertServiceFactory::createInstance(system, settings, mapContent, positionEngine);

// make a customized alert information listener to handle alert information changes
auto listener = tn::make_shared<AlertObserver>();
service->addListener(listener);

// enable alert detection
service->enableAlertDetection(true);

Disable alert detection and remove listener when it's not needed anymore.

// disable alert detection
service->enableAlertDetection(false);

// remove alert observer
service->removeListener(listener);

Make a customized alert observer to handle alert information changes.

class AlertObserver : public tn::alert::AlertListener
{
public:
    void onAlertInfoUpdate(const tn::alert::AlertInfo& alertInfo) override
    {
        const auto& alerts = alertInfo.aheadAlerts();

        for (const auto& alert : alerts) 
        {
            const auto& type = alert->type();
            if (type.isSpeedCamera())
            {
                const auto speedCameraAlert = tn::dynamic_pointer_cast<tn::alert::SpeedCameraAlert>(alert);
                // handle speed camera alert information
            }
            else 
            {
                // handle other types
            }
        }
    }
};

Highway information

Alert service provides highway information including highway names, shield icons and exits. Setup an alert service with highway information detection enabled.

// system instance is created for sharing in the whole SDK
// settings instance should be created if any default setting does not meet the requirements, could be nullptr if default values are good enough
// mapContent instance is created for sharing in the whole SDK
// positionEngine instance is created for sharing in drive session services
auto service = tn::alert::AlertServiceFactory::createInstance(system, settings, mapContent, positionEngine);

// make a customized alert information listener to handle highway information changes
auto listener = tn::make_shared<AlertObserver>();
service->addListener(listener);

// enable highway information detection
service->enableHighwayInfoDetection(true);

Disable highway information detection and remove listener when it's not needed anymore.

// disable highway information detection
service->enableHighwayInfoDetection(false);

// remove alert observer
service->removeListener(listener);

Make a customized alert observer to handle highway information changes.

class AlertObserver : public tn::alert::AlertListener
{
public:
    void onHighwayInfoUpdate(const tn::alert::HighwayInfo& highwayInfo) override
    {
        const auto& items = highwayInfo.aheadItems();

        for (const auto& item : items) 
        {
            // handle highway information            
        }
    }
};

User position information

Alert service notifies administrative level, time zone, road name, next/previous intersection name, house number and shield icon of the vehicle they are driving on. The maximum road detected limit is 3 km. Setup an alert service with user position detection enabled.

// system instance is created for sharing in the whole SDK
// settings instance should be created if any default setting does not meet the requirements, could be nullptr if default values are good enough
// mapContent instance is created for sharing in the whole SDK
// positionEngine instance is created for sharing in drive session services
auto service = tn::alert::AlertServiceFactory::createInstance(system, settings, mapContent, positionEngine);

// make a customized alert information listener to handle user position information changes
auto listener = tn::make_shared<AlertObserver>();
service->addListener(listener);

// enable user position detection
service->enableUserPositionDetection(true);

Disable user position detection and remove listener when it's not needed anymore.

// disable user position detection
service->enableUserPositionDetection(false);

// remove alert observer
service->removeListener(listener);

Make a customized alert observer to handle user position information changes.

class AlertObserver : public tn::alert::AlertListener
{
public:
    void onUserPositionInfoUpdate(const tn::alert::UserPositionInfo& userPositionInfo) override
    {
        // handle user position information
    }
};

Violation warning

Speed alert can provide users with the speed limit information and a speeding warning. Setup an alert service with violation warning detection enabled.

// system instance is created for sharing in the whole SDK
// settings instance should be created if any default setting does not meet the requirements, could be nullptr if default values are good enough
// mapContent instance is created for sharing in the whole SDK
// positionEngine instance is created for sharing in drive session services
auto service = tn::alert::AlertServiceFactory::createInstance(system, settings, mapContent, positionEngine);

// make a customized alert information listener to handle violation warning changes
auto listener = tn::make_shared<AlertObserver>();
service->addListener(listener);

// enable violation warning detection
service->enableViolationWarningDetection(true);

Disable violation warning detection and remove listener when it's not needed anymore.

// disable violation warning detection
service->enableViolationWarningDetection(false);

// remove alert observer
service->removeListener(listener);

Make a customized alert observer to handle violation warning changes.

class AlertObserver : public tn::alert::AlertListener
{
public:
    void onViolationWarningUpdate(const tn::alert::ViolationWarning& violationWarning) override
    {
        for (const auto& warning : violationWarning)
        {
            if (warning->type() == tn::alert::ViolationType::kOverSpeed)
            {
                const auto overSpeedWarning = tn::dynamic_pointer_cast<tn::alert::OverSpeedWarning>(warning);
                // handle overspeed warning
            }
        }
    }
};

Lane guidance information

Alert service provides lane guidance information for lane level navigation experience. In free mode, it only provides static lane information. In navigation mode, it also provides lane level navigation guidance instructions. Setup an alert service with lane guidance enabled.

// system instance is created for sharing in the whole SDK
// settings instance should be created if any default setting does not meet the requirements, could be nullptr if default values are good enough
// mapContent instance is created for sharing in the whole SDK
// positionEngine instance is created for sharing in drive session services
auto service = tn::alert::AlertServiceFactory::createInstance(system, settings, mapContent, positionEngine);

// make a customized alert information listener to handle lane guidance changes
auto listener = tn::make_shared<AlertObserver>();
service->addListener(listener);

// enable lane guidance
service->enableLaneGuidanceDetection(true);

Disable lane guidance and remove listener when it's not needed anymore.

// disable lane guidance
service->enableLaneGuidanceDetection(false);

// remove alert observer
service->removeListener(listener);

Make a customized alert observer to handle lane guidance.

class AlertObserver : public tn::alert::AlertListener
{
public:
    void onLaneGuidanceInfoUpdate(const tn::alert::LaneGuidanceInfo& laneGuidanceInfo) override
    {
        for (const auto& info : laneGuidanceInfo)
        {
            const auto guidanceType = info->type();
            if (guidanceType == tn::alert::LaneGuidanceType::kLaneMerge)
            {
                const auto mergeType = info->mergeType();
                // handle lane merge cases
            }
            else if (guidanceType == tn::alert::LaneGuidanceType::kLaneFork)
            {
                const auto forkType = info->forkType();
                // handle lane fork cases
            }

            const auto prevLanes = info->prevLanes();
            const auto nextLanes = info->nextLanes();
            const auto connectivity = info->connectivity();
            // handle connectivity between previous and next lanes
        }
    }
};