Added in API level 28

Builder

class Builder
kotlin.Any
   ↳ android.telephony.SubscriptionPlan.Builder

Builder for a SubscriptionPlan.

Summary

Public methods
open SubscriptionPlan!

open static SubscriptionPlan.Builder

Start defining a template for a non-recurring SubscriptionPlan with a specific duration.
open static SubscriptionPlan.Builder!

Start defining a SubscriptionPlan that covers a very specific window of time, and never automatically recurs.
open static SubscriptionPlan.Builder!
createRecurring(start: ZonedDateTime!, period: Period!)

Start defining a SubscriptionPlan that starts at a specific time, and automatically recurs after each specific period of time, repeating indefinitely.
open SubscriptionPlan.Builder

Reset any network types that were set with setNetworkTypes(int[]).
open SubscriptionPlan.Builder!
setDataLimit(dataLimitBytes: Long, dataLimitBehavior: Int)

Set the usage threshold at which data access changes.
open SubscriptionPlan.Builder!
setDataUsage(dataUsageBytes: Long, dataUsageTime: Long)

Set a snapshot of currently known mobile data usage.
open SubscriptionPlan.Builder
setDataUsageResetTime(dataUsageResetTime: ZonedDateTime?)

Sets the time when the data usage allowance will reset.
open SubscriptionPlan.Builder
setId(id: Int)

Sets the unique integer identifier for this subscription plan.
open SubscriptionPlan.Builder
setNetworkTypes(networkTypes: IntArray)

Set the network types this SubscriptionPlan applies to.
open SubscriptionPlan.Builder

Sets the maximum downstream bitrate for streaming applications on this subscription plan, in Kilobits per second (Kbps) defined in GSMA TS.
open SubscriptionPlan.Builder

Sets the maximum upstream bitrate for streaming applications on this subscription plan, in Kilobits per second (Kbps) defined in GSMA TS.
open SubscriptionPlan.Builder
setSubscriptionStatus(subscriptionStatus: Int)

Set the subscription status.
open SubscriptionPlan.Builder!

Sets a brief, human-readable summary of the subscription plan.
open SubscriptionPlan.Builder!

Sets a user-visible title for this plan.
open SubscriptionPlan.Builder

Set the types of this subscription plan.

Public methods

build

Added in API level 28
open fun build(): SubscriptionPlan!

createNonrecurring

Added in API level 28
open static fun createNonrecurring(duration: Period): SubscriptionPlan.Builder

Start defining a template for a non-recurring SubscriptionPlan with a specific duration.

This is useful for describing fixed-duration plans that users can enroll in, such as a travel pass or a one-time data package. The actual start and end dates are determined upon enrollment.

Plans created with this builder should be marked with setSubscriptionStatus(int) and a status of SUBSCRIPTION_STATUS_INACTIVE.

Parameters
duration Period: The total duration of the plan once activated (e.g., Period.ofDays(15)).
This value cannot be null.
Return
SubscriptionPlan.Builder A Builder instance for a non-recurring plan template.
This value cannot be null.

createNonrecurring

Added in API level 28
open static fun createNonrecurring(
    start: ZonedDateTime!, 
    end: ZonedDateTime!
): SubscriptionPlan.Builder!

Start defining a SubscriptionPlan that covers a very specific window of time, and never automatically recurs.

Parameters
start ZonedDateTime!: The exact time at which the plan starts.
end ZonedDateTime!: The exact time at which the plan ends.

createRecurring

Added in API level 28
open static fun createRecurring(
    start: ZonedDateTime!, 
    period: Period!
): SubscriptionPlan.Builder!

Start defining a SubscriptionPlan that starts at a specific time, and automatically recurs after each specific period of time, repeating indefinitely.

When the given period is set to exactly one month, the plan will always recur on the day of the month defined by ZonedDateTime.getDayOfMonth(). When a particular month ends before this day, the plan will recur on the last possible instant of that month.

Parameters
start ZonedDateTime!: The exact time at which the plan starts.
period Period!: The period after which the plan automatically recurs.

resetNetworkTypes

Added in API level 30
open fun resetNetworkTypes(): SubscriptionPlan.Builder

Reset any network types that were set with setNetworkTypes(int[]). This will make the SubscriptionPlan apply to all network types.

Return
SubscriptionPlan.Builder This value cannot be null.

setDataLimit

Added in API level 28
open fun setDataLimit(
    dataLimitBytes: Long, 
    dataLimitBehavior: Int
): SubscriptionPlan.Builder!

Set the usage threshold at which data access changes.

Parameters
dataLimitBytes Long: the usage threshold at which data access changes.
Value is a non-negative number of bytes.
dataLimitBehavior Int: the behavior of data access when usage reaches the threshold.
Value is one of the following:

setDataUsage

Added in API level 28
open fun setDataUsage(
    dataUsageBytes: Long, 
    dataUsageTime: Long
): SubscriptionPlan.Builder!

Set a snapshot of currently known mobile data usage.

Parameters
dataUsageBytes Long: the currently known mobile data usage.
Value is a non-negative number of bytes.
dataUsageTime Long: the time at which this snapshot was valid.
Value is a non-negative timestamp measured as the number of milliseconds since 1970-01-01T00:00:00Z.

setDataUsageResetTime

Added in API level 28
open fun setDataUsageResetTime(dataUsageResetTime: ZonedDateTime?): SubscriptionPlan.Builder

Sets the time when the data usage allowance will reset.

This is particularly relevant for plans with a daily data allowance, as it specifies the exact moment (e.g., midnight in a specific timezone) when the usage for the next 24-hour will reset. For other types of plans, this may not be applicable.

The value provided for setDataUsage(long,long) should reflect the data consumed since the last reset time.

Parameters
dataUsageResetTime ZonedDateTime?: The data usage reset time, or null if this information is not available or not applicable to the plan.
Return
SubscriptionPlan.Builder This value cannot be null.

setId

Added in API level 28
open fun setId(id: Int): SubscriptionPlan.Builder

Sets the unique integer identifier for this subscription plan.

This ID is provided by the carrier and can be used to uniquely identify this plan, particularly when interacting with entitlement server for enrolling.

Parameters
id Int: The unique integer integer identifier for the plan, or UNSPECIFIED_ID to clear it.
Return
SubscriptionPlan.Builder The same Builder instance to continue building the plan.
This value cannot be null.

setNetworkTypes

Added in API level 30
open fun setNetworkTypes(networkTypes: IntArray): SubscriptionPlan.Builder

Set the network types this SubscriptionPlan applies to. By default the plan will apply to all network types. An empty array means this plan applies to no network types.

Parameters
networkTypes IntArray: an array of all network types that apply to this plan.
This value cannot be null.
Value is one of the following:
Return
SubscriptionPlan.Builder This value cannot be null.

See Also

    setStreamingAppMaxDownlinkKbps

    Added in API level 28
    open fun setStreamingAppMaxDownlinkKbps(downlinkKbps: Long): SubscriptionPlan.Builder

    Sets the maximum downstream bitrate for streaming applications on this subscription plan, in Kilobits per second (Kbps) defined in GSMA TS.43 9.1.3.

    Parameters
    downlinkKbps Long: The maximum downstream bandwidth in Kbps.
    Return
    SubscriptionPlan.Builder This value cannot be null.

    setStreamingAppMaxUplinkKbps

    Added in API level 28
    open fun setStreamingAppMaxUplinkKbps(uplinkKbps: Long): SubscriptionPlan.Builder

    Sets the maximum upstream bitrate for streaming applications on this subscription plan, in Kilobits per second (Kbps) defined in GSMA TS.43 9.1.3.

    Parameters
    uplinkKbps Long: The maximum upstream bitrate in Kbps.
    Return
    SubscriptionPlan.Builder This value cannot be null.

    setSubscriptionStatus

    Added in API level 36
    open fun setSubscriptionStatus(subscriptionStatus: Int): SubscriptionPlan.Builder

    Set the subscription status.

    This indicates the current state of the subscription, such as whether it is active, suspended, or in a trial period. This status provides context on the plan's availability and can be used to inform the user about their subscription's lifecycle.

    Parameters
    subscriptionStatus Int: the current subscription status.
    Value is one of the following:
    Return
    SubscriptionPlan.Builder This value cannot be null.

    setSummary

    Added in API level 28
    open fun setSummary(summary: CharSequence?): SubscriptionPlan.Builder!

    Sets a brief, human-readable summary of the subscription plan.

    This could include details about the plan's features, such as "10GB of high-speed data" or "Unlimited talk and text". This summary is intended for display to the user.

    Parameters
    summary CharSequence?: A short, user-friendly summary of the plan, or null to clear it.

    setTitle

    Added in API level 28
    open fun setTitle(title: CharSequence?): SubscriptionPlan.Builder!

    Sets a user-visible title for this plan.

    This title is provided by the carrier to identify the subscription plan, for example, "Unlimited+" or "Family plan". It is intended for display to the user.

    Parameters
    title CharSequence?: The title of the plan.
    This value may be null.
    Return
    SubscriptionPlan.Builder! The same Builder instance to continue building the plan.

    setTypes

    Added in API level 28
    open fun setTypes(types: IntArray): SubscriptionPlan.Builder

    Set the types of this subscription plan. A plan can have multiple types, and this method will return all that are applicable. For example, a plan could be both a cellular plan and a postpaid plan.

    Parameters
    types IntArray: This value cannot be null.
    Value is one of the following:
    Return
    SubscriptionPlan.Builder An array containing the applicable PLAN_TYPE_ constants.
    This value cannot be null.