Smart Locations

Smart Locations are designed to identify the fastest servers tailored for individual customers. The definition of "fast" encompasses a variety of factors, which are detailed in the implementation of the Smart Location Algorithm.

Caching for Smart Locations

The SDK will internally cache smart locations for 30 days. It will internally use

• Country
• Region
• ISP Name
• Autonomous System Number (ASN)
• WiFi SSID or Network Name
• WiFi BSSID or Network Name

It will therefore rely on the get_user_location() method, to obtain the user's current network parameters. As these network parameters cached as well, it's important to tell the SDK, of the user's network change by calling the SDK Manager networkChanged() method.

However, the SDK can't obtain the WiFi SSID or BSSID, so it's important that apps keep this values up to date when switching between networks, by updating the SDK Managers configuration object:

let config = kapeSDKManager.getConfiguration()
//WiFi SSID of the current network
config.setCurrentNetworkName("Starbucks")
//WIFI BSSID of the current network
config.setCurrentNetworkName("aa::bb:cc::dd:ee:ff")

In a Non-WiFi environment, the network name could the Windows Network Profile Name and the network id could be the mac address of the router. These parameters are optional and just help to further segment the cache results.

Matching cached records

The internal Network Cache Manager uses a multi-step logic to match a cached result with the current network of the user.

1. Try to match Country, Region, ISP, ASN, SSID, BSSID if no results returned continue with 2.
2. Try to match Country, Region, ISP, ASN, SSID, if no results returned continue with 3.
3. Try to match Country, Region, ISP, if no results returned continue with 4.
4. Try to match Country, Region, if not results returned continue with 5.
5. Try to match Country, if no results returned RETURN NO ENTRY else continue with 6.
6. If results are returned, use the most recent result, determined by the date and time they’ve been added

has_smart_locations

Returns whether there are cached, non-expired Smart Location results for the current network. This uses exact matching only — no fuzzy fallback. If networkName/networkId are not set in the configuration, matching stops at the ASN level.

This allows the host app to determine whether a Smart Location test needs to be run before showing the server list.

Parameters

None. Network parameters are read from the configuration.

Returns

Bool — true if valid cached results exist, false otherwise.

---

has_preferred_protocol

Returns whether there are cached, non-expired Preferred Protocol results for the current network.

Parameters

Name	Type	Description
for_location	String?	If provided, checks for that specific location. If nil/null, checks for any cached entry.

Returns

Bool — true if valid cached results exist, false otherwise.

---

get_smart_locations

This method will return the fasted locations for the user's current network parameters from all available locations contained in his subscription.

warning

If the user is currently connected to the VPN, a Smart Location measurement cannot be performed. In this case, the method will fail if no cached Smart Location is available or if a refresh is explicitly requested.

warning

You can't run this method multiple times simultaneously as the measurements would interfer with each other. The SDK will prevent that multiple instances are running and will return an exception.

Parameters

Name	Type	Description
subscription_id	String	ID of the subscription which has a VPN entitlement. You can obtain that subscription id as described in Obtaining a VPN Subscription ID
refresh	Bool	If false, Smart Locations will be returned from the cache if available. If no cached Smart Location will be found, a new measurement will be performed. If true, the cache will be ignored and a new measurement will be made. This is usually used, if the user "pulls to refresh" in the server list. This will also automatically refresh the user's current network parameters.

Returns

LocationRatingResult upon success or InstanceDiscoveryException otherwise.

LocationRatingResult

Internally, the final rating of a location will be calculated from 4 different measurements:

• Physical Distance
• Ping Measurement (Latency, Jitter, Packet Loss)
• HTTP Up- and Download Measurements (Bandwidth)

info

Note: Not all rating types might be available in a result. E.g. if a ping rating failed, HTTP Ratings will not be provided as well, as the HTTP measurement will be based on the endpoint of a location which provided the best ping result.

Name	Type	Description
location_id	String	Unique ID of the location
distance_rating	DistanceRating (optional)	This contains details about the physical distance between user location and server location
ping_rating	PingRating (optional)	This contains details about the ping measurements like latency, jitter and packet loss.
download_rating	HttpRating (optional)	This contains details about the HTTP download measurement
upload_rating	HttpRating (optional)	This contains details about the HTTP upload measurement
final_rating_category	RatingCategory	This is the final rating, based on the above weighted ratings. Excellent = 5, Good = 4, Ok = 3, Degraded = 2, Poor = 1, Unknown = 0,