or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-configuration.mddata-protection.mdindex.mdmessage-publishing.mdpagination.mdpermission-management.mdplatform-applications.mdresource-tagging.mdsms-management.mdsubscription-management.mdtopic-management.md
tile.json

platform-applications.mddocs/

Platform Applications and Endpoints

SNS platform applications enable mobile push notifications to iOS, Android, and other mobile platforms. This system manages platform applications that represent mobile apps and endpoints that represent individual devices.

Capabilities

Create Platform Application

Creates a platform application for mobile push notifications with platform-specific configuration.

/**
 * Creates a platform application object for push notification services
 * Represents a mobile app registered with a push notification service
 */
class CreatePlatformApplicationCommand {
  constructor(input: CreatePlatformApplicationInput);
}

interface CreatePlatformApplicationInput {
  /** Name of the platform application */
  Name: string;
  /** Push notification platform identifier */
  Platform: string;
  /** Platform-specific configuration attributes */
  Attributes: PlatformApplicationAttributesMap;
}

interface CreatePlatformApplicationResponse {
  /** ARN of the created platform application */
  PlatformApplicationArn?: string;
}

interface PlatformApplicationAttributesMap {
  [key: string]: string;
}

Supported Platforms:

  • APNS - Apple Push Notification Service (iOS)
  • APNS_SANDBOX - Apple Push Notification Service Sandbox
  • GCM - Google Cloud Messaging (Android)
  • ADM - Amazon Device Messaging
  • BAIDU - Baidu Cloud Push
  • MPNS - Microsoft Push Notification Service
  • WNS - Windows Push Notification Service
  • MACOS - macOS notifications
  • MACOS_SANDBOX - macOS sandbox notifications

Platform-Specific Examples:

import { SNSClient, CreatePlatformApplicationCommand } from "@aws-sdk/client-sns";

const client = new SNSClient({ region: "us-east-1" });

// iOS APNS Application
const iosApp = await client.send(new CreatePlatformApplicationCommand({
  Name: "MyiOSApp",
  Platform: "APNS",
  Attributes: {
    PlatformCredential: "your-apns-private-key",
    PlatformPrincipal: "your-apns-certificate"
  }
}));

// iOS APNS with Token-based Authentication
const iosTokenApp = await client.send(new CreatePlatformApplicationCommand({
  Name: "MyiOSTokenApp", 
  Platform: "APNS",
  Attributes: {
    PlatformCredential: "your-apns-auth-key",
    PlatformPrincipal: "your-team-id",
    ApplePlatformTeamID: "your-team-id",
    ApplePlatformBundleID: "com.example.myapp"
  }
}));

// Android GCM Application
const androidApp = await client.send(new CreatePlatformApplicationCommand({
  Name: "MyAndroidApp",
  Platform: "GCM", 
  Attributes: {
    PlatformCredential: "your-gcm-api-key"
  }
}));

// Amazon Device Messaging
const admApp = await client.send(new CreatePlatformApplicationCommand({
  Name: "MyKindleApp",
  Platform: "ADM",
  Attributes: {
    PlatformCredential: "your-adm-client-secret",
    PlatformPrincipal: "your-adm-client-id"
  }
}));

// Windows Push Notification Service
const wnsApp = await client.send(new CreatePlatformApplicationCommand({
  Name: "MyWindowsApp",
  Platform: "WNS",
  Attributes: {
    PlatformCredential: "your-wns-client-secret",
    PlatformPrincipal: "your-wns-package-sid"
  }
}));

Delete Platform Application

Deletes a platform application and all its associated endpoints.

/**
 * Deletes a platform application and all its endpoints
 * This action cannot be undone
 */
class DeletePlatformApplicationCommand {
  constructor(input: DeletePlatformApplicationInput);
}

interface DeletePlatformApplicationInput {
  /** ARN of the platform application to delete */
  PlatformApplicationArn: string;
}

Usage Example:

await client.send(new DeletePlatformApplicationCommand({
  PlatformApplicationArn: "arn:aws:sns:us-east-1:123456789012:app/APNS/MyiOSApp"
}));

Get Platform Application Attributes

Retrieves attributes and configuration for a platform application.

/**
 * Returns platform application attributes including credentials and statistics
 */
class GetPlatformApplicationAttributesCommand {
  constructor(input: GetPlatformApplicationAttributesInput);
}

interface GetPlatformApplicationAttributesInput {
  /** ARN of the platform application */
  PlatformApplicationArn: string;
}

interface GetPlatformApplicationAttributesResponse {
  /** Map of attribute names to values */
  Attributes?: PlatformApplicationAttributesMap;
}

Common Platform Application Attributes:

  • PlatformCredential: Platform-specific credential (API key, certificate, etc.)
  • PlatformPrincipal: Platform-specific principal (certificate, client ID, etc.)
  • EventEndpointCreated: Topic ARN for endpoint creation events
  • EventEndpointDeleted: Topic ARN for endpoint deletion events
  • EventEndpointUpdated: Topic ARN for endpoint update events
  • EventDeliveryFailure: Topic ARN for delivery failure events
  • EventDeliveryAttemptFailure: Topic ARN for delivery attempt failure events
  • SuccessFeedbackRoleArn: IAM role for success feedback
  • FailureFeedbackRoleArn: IAM role for failure feedback
  • SuccessFeedbackSampleRate: Success feedback sampling rate

Usage Example:

const attributes = await client.send(new GetPlatformApplicationAttributesCommand({
  PlatformApplicationArn: "arn:aws:sns:us-east-1:123456789012:app/APNS/MyiOSApp"
}));

console.log("Platform:", attributes.Attributes?.Platform);
console.log("Enabled:", attributes.Attributes?.Enabled);

Set Platform Application Attributes

Modifies attributes for an existing platform application.

/**
 * Sets an attribute for a platform application
 * Allows modification of credentials and configuration
 */
class SetPlatformApplicationAttributesCommand {
  constructor(input: SetPlatformApplicationAttributesInput);
}

interface SetPlatformApplicationAttributesInput {
  /** ARN of the platform application */
  PlatformApplicationArn: string;
  /** Map of attributes to set */
  Attributes: PlatformApplicationAttributesMap;
}

Usage Examples:

// Update APNS credentials
await client.send(new SetPlatformApplicationAttributesCommand({
  PlatformApplicationArn: "arn:aws:sns:us-east-1:123456789012:app/APNS/MyiOSApp",
  Attributes: {
    PlatformCredential: "new-apns-private-key",
    PlatformPrincipal: "new-apns-certificate"
  }
}));

// Configure event notifications
await client.send(new SetPlatformApplicationAttributesCommand({
  PlatformApplicationArn: "arn:aws:sns:us-east-1:123456789012:app/APNS/MyiOSApp",
  Attributes: {
    EventEndpointCreated: "arn:aws:sns:us-east-1:123456789012:EndpointEvents",
    EventDeliveryFailure: "arn:aws:sns:us-east-1:123456789012:DeliveryFailures",
    SuccessFeedbackRoleArn: "arn:aws:iam::123456789012:role/SNSSuccessFeedback",
    SuccessFeedbackSampleRate: "10"
  }
}));

List Platform Applications

Lists all platform applications in the account with pagination support.

/**
 * Returns a list of platform applications
 * Supports pagination for large numbers of applications
 */
class ListPlatformApplicationsCommand {
  constructor(input?: ListPlatformApplicationsInput);
}

interface ListPlatformApplicationsInput {
  /** Pagination token from previous request */
  NextToken?: string;
}

interface ListPlatformApplicationsResponse {
  /** Array of platform application information */
  PlatformApplications?: PlatformApplication[];
  /** Token for next page of results */
  NextToken?: string;
}

interface PlatformApplication {
  /** ARN of the platform application */
  PlatformApplicationArn?: string;
  /** Platform application attributes */
  Attributes?: PlatformApplicationAttributesMap;
}

Usage Example:

const applications = await client.send(new ListPlatformApplicationsCommand());
applications.PlatformApplications?.forEach(app => {
  console.log("Application ARN:", app.PlatformApplicationArn);
  console.log("Platform:", app.Attributes?.Platform);
});

Create Platform Endpoint

Creates an endpoint for a device registered with a platform application.

/**
 * Creates an endpoint for device registration with a platform application
 * Represents a single device that can receive push notifications
 */
class CreatePlatformEndpointCommand {
  constructor(input: CreatePlatformEndpointInput);
}

interface CreatePlatformEndpointInput {
  /** ARN of the platform application */
  PlatformApplicationArn: string;
  /** Device token from the platform */
  Token: string;
  /** Custom identifier for the endpoint */
  CustomUserData?: string;
  /** Endpoint attributes */
  Attributes?: EndpointAttributesMap;
}

interface CreateEndpointResponse {
  /** ARN of the created endpoint */
  EndpointArn?: string;
}

interface EndpointAttributesMap {
  [key: string]: string;
}

Usage Examples:

// iOS device endpoint
const iosEndpoint = await client.send(new CreatePlatformEndpointCommand({
  PlatformApplicationArn: "arn:aws:sns:us-east-1:123456789012:app/APNS/MyiOSApp",
  Token: "device-push-token-from-ios",
  CustomUserData: "user-12345",
  Attributes: {
    Enabled: "true"
  }
}));

// Android device endpoint  
const androidEndpoint = await client.send(new CreatePlatformEndpointCommand({
  PlatformApplicationArn: "arn:aws:sns:us-east-1:123456789012:app/GCM/MyAndroidApp",
  Token: "fcm-registration-token",
  CustomUserData: JSON.stringify({
    userId: "user-67890",
    deviceType: "android",
    appVersion: "2.1.0"
  })
}));

Delete Endpoint

Deletes a platform endpoint and stops message delivery to that device.

/**
 * Deletes an endpoint for a device
 * Removes device from receiving push notifications
 */
class DeleteEndpointCommand {
  constructor(input: DeleteEndpointInput);
}

interface DeleteEndpointInput {
  /** ARN of the endpoint to delete */
  EndpointArn: string;
}

Usage Example:

await client.send(new DeleteEndpointCommand({
  EndpointArn: "arn:aws:sns:us-east-1:123456789012:endpoint/APNS/MyiOSApp/device-id"
}));

Get Endpoint Attributes

Retrieves attributes and status information for a platform endpoint.

/**
 * Returns endpoint attributes including device information and status
 */
class GetEndpointAttributesCommand {
  constructor(input: GetEndpointAttributesInput);
}

interface GetEndpointAttributesInput {
  /** ARN of the endpoint */
  EndpointArn: string;
}

interface GetEndpointAttributesResponse {
  /** Map of attribute names to values */
  Attributes?: EndpointAttributesMap;
}

Common Endpoint Attributes:

  • CustomUserData: Custom data associated with the endpoint
  • Enabled: Whether the endpoint is enabled ("true" or "false")
  • Token: Device token from the push notification service
  • UserId: User identifier associated with the endpoint

Usage Example:

const endpointInfo = await client.send(new GetEndpointAttributesCommand({
  EndpointArn: "arn:aws:sns:us-east-1:123456789012:endpoint/APNS/MyiOSApp/device-id"
}));

console.log("Enabled:", endpointInfo.Attributes?.Enabled);
console.log("Token:", endpointInfo.Attributes?.Token);
console.log("User Data:", endpointInfo.Attributes?.CustomUserData);

Set Endpoint Attributes

Modifies attributes for an existing platform endpoint.

/**
 * Sets attributes for an endpoint
 * Allows updating device token and other endpoint configuration
 */
class SetEndpointAttributesCommand {
  constructor(input: SetEndpointAttributesInput);
}

interface SetEndpointAttributesInput {
  /** ARN of the endpoint */
  EndpointArn: string;
  /** Map of attributes to set */
  Attributes: EndpointAttributesMap;
}

Usage Examples:

// Update device token
await client.send(new SetEndpointAttributesCommand({
  EndpointArn: "arn:aws:sns:us-east-1:123456789012:endpoint/APNS/MyiOSApp/device-id",
  Attributes: {
    Token: "new-device-token",
    Enabled: "true"
  }
}));

// Disable endpoint
await client.send(new SetEndpointAttributesCommand({
  EndpointArn: "arn:aws:sns:us-east-1:123456789012:endpoint/APNS/MyiOSApp/device-id",
  Attributes: {
    Enabled: "false"
  }
}));

List Endpoints by Platform Application

Lists all endpoints for a specific platform application.

/**
 * Returns a list of endpoints for a platform application
 * Useful for managing devices registered with an app
 */
class ListEndpointsByPlatformApplicationCommand {
  constructor(input: ListEndpointsByPlatformApplicationInput);
}

interface ListEndpointsByPlatformApplicationInput {
  /** ARN of the platform application */
  PlatformApplicationArn: string;
  /** Pagination token from previous request */
  NextToken?: string;
}

interface ListEndpointsByPlatformApplicationResponse {
  /** Array of endpoint information */
  Endpoints?: Endpoint[];
  /** Token for next page of results */
  NextToken?: string;
}

interface Endpoint {
  /** ARN of the endpoint */
  EndpointArn?: string;
  /** Endpoint attributes */
  Attributes?: EndpointAttributesMap;
}

Usage Example:

const endpoints = await client.send(new ListEndpointsByPlatformApplicationCommand({
  PlatformApplicationArn: "arn:aws:sns:us-east-1:123456789012:app/APNS/MyiOSApp"
}));

endpoints.Endpoints?.forEach(endpoint => {
  console.log("Endpoint ARN:", endpoint.EndpointArn);
  console.log("Enabled:", endpoint.Attributes?.Enabled);
  console.log("Token:", endpoint.Attributes?.Token);
});

Platform-Specific Configuration

Apple Push Notification Service (APNS)

Configuration for iOS push notifications with both certificate and token-based authentication.

Certificate-based Authentication:

const apnsApp = await client.send(new CreatePlatformApplicationCommand({
  Name: "MyiOSApp",
  Platform: "APNS",
  Attributes: {
    PlatformCredential: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    PlatformPrincipal: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  }
}));

Token-based Authentication (Recommended):

const apnsTokenApp = await client.send(new CreatePlatformApplicationCommand({
  Name: "MyiOSTokenApp",
  Platform: "APNS", 
  Attributes: {
    PlatformCredential: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    PlatformPrincipal: "TEAM12345678",
    ApplePlatformTeamID: "TEAM12345678", 
    ApplePlatformBundleID: "com.example.myapp"
  }
}));

Google Cloud Messaging (GCM/FCM)

Configuration for Android push notifications using Firebase Cloud Messaging.

const gcmApp = await client.send(new CreatePlatformApplicationCommand({
  Name: "MyAndroidApp",
  Platform: "GCM",
  Attributes: {
    PlatformCredential: "your-fcm-server-key"
  }
}));

Amazon Device Messaging (ADM)

Configuration for Kindle Fire and other Amazon devices.

const admApp = await client.send(new CreatePlatformApplicationCommand({
  Name: "MyKindleApp", 
  Platform: "ADM",
  Attributes: {
    PlatformCredential: "your-adm-client-secret",
    PlatformPrincipal: "your-adm-client-id"
  }
}));

Common Mobile Push Patterns

Device Registration Flow:

const registerDevice = async (
  platformAppArn: string, 
  deviceToken: string, 
  userId: string
) => {
  try {
    // Try to create new endpoint
    const endpoint = await client.send(new CreatePlatformEndpointCommand({
      PlatformApplicationArn: platformAppArn,
      Token: deviceToken,
      CustomUserData: userId
    }));
    
    return endpoint.EndpointArn;
  } catch (error) {
    // Handle duplicate token by updating existing endpoint
    if (error.name === 'InvalidParameterException') {
      // Extract endpoint ARN from error and update token
      const endpointArn = extractEndpointFromError(error);
      await client.send(new SetEndpointAttributesCommand({
        EndpointArn: endpointArn,
        Attributes: {
          Token: deviceToken,
          Enabled: "true"
        }
      }));
      return endpointArn;
    }
    throw error;
  }
};

Send Platform-Specific Push Notification:

import { PublishCommand } from "@aws-sdk/client-sns";

const sendPushNotification = async (endpointArn: string, alert: string, badge?: number) => {
  const platform = endpointArn.includes('/APNS/') ? 'APNS' : 'GCM';
  
  let message;
  if (platform === 'APNS') {
    message = {
      APNS: JSON.stringify({
        aps: {
          alert: alert,
          badge: badge || 0,
          sound: "default"
        }
      })
    };
  } else {
    message = {
      GCM: JSON.stringify({
        notification: {
          title: "Notification",
          body: alert
        },
        data: {
          badge: (badge || 0).toString()
        }
      })
    };
  }
  
  await client.send(new PublishCommand({
    TargetArn: endpointArn,
    Message: JSON.stringify(message),
    MessageStructure: "json"
  }));
};

Bulk Endpoint Management:

const cleanupDisabledEndpoints = async (platformAppArn: string) => {
  let nextToken: string | undefined;
  
  do {
    const result = await client.send(new ListEndpointsByPlatformApplicationCommand({
      PlatformApplicationArn: platformAppArn,
      NextToken: nextToken
    }));
    
    for (const endpoint of result.Endpoints || []) {
      if (endpoint.Attributes?.Enabled === "false") {
        await client.send(new DeleteEndpointCommand({
          EndpointArn: endpoint.EndpointArn!
        }));
        console.log(`Deleted disabled endpoint: ${endpoint.EndpointArn}`);
      }
    }
    
    nextToken = result.NextToken;
  } while (nextToken);
};