Checking roaming status

The Device Status SDK allows checking the device roaming status and subscribing to its related events. A device can be in national (different networks in the same country) or international roaming (different networks in another country). Knowing whether device is connected to a network other than its home one is important for regulatory, security and content delivery reasons.

For example, in some cases for certain transactions to take place, a device needs to be within an area where it is legally allowed to operate or make transactions. Another case would be to ensure a customer's device is exactly where it claims to be to avoid fraud. Other important examples include content or service delivery to avoid extra costs or unexpected roaming charges for accessing them.

Getting device roaming status

The SDK below allows you to subscribe client devices to Device Status roaming events.

import network_as_code as nac
from datetime import datetime, timedelta, timezone
from network_as_code.models.device import Device, DeviceIpv4Addr
 
client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)
 
# Create a device object for the mobile device we want to use
my_device = client.devices.get(
    "device@testcsp.net",
    ipv4_address = DeviceIpv4Addr(
        public_address="192.0.2.3",
        private_address="192.0.2.204",
        public_port=80
    ),
    ipv6_address = "2001:db8:1234:5678:9abc:def0:fedc:ba98",
    phone_number = "36721601234567"
)
 
# Simply change the event_type to
# "org.camaraproject.device-status.v0.connectivity-data" whenever needed.
my_subscription = client.connectivity.subscribe(
    event_type="org.camaraproject.device-status.v0.roaming-status",
    device=my_device,
    # You can tell when the subscription is suposed to expire
    subscription_expire_time="2024-04-10T14:13:29Z",
    # Use HTTPS to send notifications
    notification_url="https://example.com/notifications",
    notification_auth_token="<your-token-here>"
)
 
# Use this to show the roaming subscription status
print(my_subscription)
 
# Or check when your subscription starts/expires:
print(my_subscription.starts_at)
print(my_subscription.expires_at)

NOTE: The subscription expire time can be defined with an ISO 8601 formatted date string, for example "2024-03-28T12:40:20.398Z", or simply create a date-time object as shown in the code snippet examples above.

Device object parameters

The snippet above identified a mobile network device in multiple ways (IP addresses, port, etc). Learn how to create a device object and understand how the DeviceIPv4Addr model works using NAT technology.

Roaming subscription parameters

Above, we created a Subscription object for roaming status and supplied the necessary parameters to the roaming-subscription method. The parameters table below describes which data each parameter expects to receive.

ParametersDescription
event_typeThe status type you want to check, which can be connectivity or roaming.
deviceDevice ID callback parameter.
max_num_of_reportsHow many reports will be sent to the endpoint.
notification_urlThe recipient's HTTP endpoint, which is a web server configured to receive POST requests.
notification_auth_tokenA password used to identify the sender of the notification.
subscription_expire_timeThe expiry time of the subscription. Either a date-time object or ISO 8601 formatted date string.

Last updated on May 23, 2024