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.

It also creates a Network as Code client using an application key accessible from your Dashboard and identifies a mobile network device in multiple ways (IP addresses, port, etc). Learn more about the client and device objects.

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 supposed 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.

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.