Go SDK 8.0.0 Migration Guide

This guide summarizes the differences between versions 7.x.x and 8.0.0 and shows how to migrate to Go SDK 8.0.0.

Go SDK version 8.0.0 modernizes push notification support, enhances file messaging capabilities, and introduces pagination for presence operations. This release removes deprecated features and fixes inconsistencies in the API.

No Go SDK 7.x.x support

If your application uses Go SDK 7.x.x, it continues to work. We recommend migrating to Go 8.0.0 to access new features and improvements. Version 7.x.x receives only critical security fixes.

What has changed

See the major differences between versions:

Feature/Method	Go SDK 7.x.x	Go SDK 8.0.0
Push notification types	PNPushTypeMPNS, PNPushTypeGCM, PNPushTypeAPNS, PNPushTypeAPNS2	PNPushTypeFCM (new), PNPushTypeAPNS2 Removed: PNPushTypeMPNS Deprecated: PNPushTypeGCM, PNPushTypeAPNS
PNPublishMessage.Text type	string	interface{}
SendFile ShouldStore behavior fix	always true	false (but configurable)
Fetch Reverse parameter	Supported (but not functional)	Removed
HereNow occupant limit	Unlimited	1,000 (with pagination support)

Breaking changes

Push notification types

Go SDK 8.0.0 removes PNPushTypeMPNS and deprecates PNPushTypeGCM and PNPushTypeAPNS. Use PNPushTypeFCM for Firebase Cloud Messaging or PNPushTypeAPNS2 for Apple Push Notification service.

MPNS removed

Microsoft Push Notification Service (MPNS) is no longer supported. If your app uses PNPushTypeMPNS, migrate to FCM or APNs2.

Before (v7.x.x)

// Using GCM (now deprecated)
res, status, err := pn.AddPushNotificationsOnChannels().
    Channels([]string{"channel1", "channel2"}).
    DeviceIDForPush("device-token").
    PushType(pubnub.PNPushTypeGCM).
    Execute()


// Using APNs (now deprecated)
res, status, err := pn.AddPushNotificationsOnChannels().
    Channels([]string{"channel1", "channel2"}).
    DeviceIDForPush("device-token").
    PushType(pubnub.PNPushTypeAPNS).
    Execute()


// Using MPNS (now removed)
res, status, err := pn.AddPushNotificationsOnChannels().
    Channels([]string{"channel1", "channel2"}).
    DeviceIDForPush("device-token").
    PushType(pubnub.PNPushTypeMPNS).
    Execute()

show all 20 lines

After (v8.x.x)

// Use FCM for Firebase Cloud Messaging
res, status, err := pn.AddPushNotificationsOnChannels().
    Channels([]string{"channel1", "channel2"}).
    DeviceIDForPush("device-token").
    PushType(pubnub.PNPushTypeFCM).
    Execute()


// Use APNs2 for Apple Push Notification service
res, status, err := pn.AddPushNotificationsOnChannels().
    Channels([]string{"channel1", "channel2"}).
    DeviceIDForPush("device-token").
    PushType(pubnub.PNPushTypeAPNS2).
    Topic("com.example.app").
    Execute()

This change affects all push notification methods:

• AddPushNotificationsOnChannels
• RemovePushNotificationsFromChannels
• RemoveAllPushNotificationsFromDeviceWithPushToken
• ListPushProvisions

File message text type

PNPublishMessage.Text now accepts interface{} instead of string. This enables sending arbitrary JSON types in file messages.

Before (v7.x.x)

// Text field only accepted strings
msg := pubnub.PNPublishMessage{
    Text: "Hello, file attached!",
}


res, status, err := pn.PublishFileMessage().
    Channel("channel1").
    Message(msg).
    FileID("file-id").
    FileName("document.pdf").
    Execute()

After (v8.x.x)

// Text field now accepts any type
msg := pubnub.PNPublishMessage{
    Text: map[string]interface{}{
        "message": "Hello, file attached!",
        "metadata": map[string]interface{}{
            "sender": "user123",
            "timestamp": time.Now().Unix(),
        },
    },
}


res, status, err := pn.PublishFileMessage().
    Channel("channel1").
    Message(msg).
    FileID("file-id").
    FileName("document.pdf").
    Execute()


// Strings still work
msgString := pubnub.PNPublishMessage{
    Text: "Simple text message",
}

show all 22 lines

SendFile ShouldStore behavior fix

The ShouldStore parameter in SendFile now correctly manages whether the file message is stored in Message Persistence.

Before (v7.x.x)

// Files were stored by default
res, status, err := pn.SendFile().
    Channel("channel1").
    Message("Check this file").
    File(file).
    FileName("document.pdf").
    Execute()
// Message stored in history by default

After (v8.x.x)

// Files are NOT stored by default
res, status, err := pn.SendFile().
    Channel("channel1").
    Message("Check this file").
    File(file).
    FileName("document.pdf").
    ShouldStore(true). // Explicitly enable storage
    Execute()

Fetch Reverse parameter removed

The Reverse parameter is removed from the Fetch method.

Before (v7.x.x)

res, status, err := pn.Fetch().
    Channels([]string{"channel1", "channel2"}).
    Maximum(25).
    Reverse(true). // This parameter is removed
    Execute()

After (v8.x.x)

res, status, err := pn.Fetch().
    Channels([]string{"channel1", "channel2"}).
    Maximum(25).
    Execute()

If you need messages in reverse order, process the results in your application code:

res, status, err := pn.Fetch().
    Channels([]string{"channel1", "channel2"}).
    Maximum(25).
    Execute()


if err == nil {
    messages := res.Messages["channel1"]
    // Reverse the slice in your application
    for i, j := 0, len(messages)-1; i < j; i, j = i+1, j-1 {
        messages[i], messages[j] = messages[j], messages[i]
    }
}

HereNow pagination

HereNow now returns a maximum of 1,000 occupants per channel. Use pagination to retrieve more occupants.

Occupant limit

If your channels have more than 1,000 occupants, your application must use pagination to retrieve the complete list.

Before (v7.x.x)

// All occupants returned (no limit)
res, status, err := pn.HereNow().
    Channels([]string{"channel1"}).
    IncludeUUIDs(true).
    IncludeState(true).
    Execute()


// All occupants available in res
fmt.Printf("Total occupants: %d\n", res.TotalOccupancy)

After (v8.x.x)

// Maximum 1,000 occupants returned
res, status, err := pn.HereNow().
    Channels([]string{"channel1"}).
    IncludeUUIDs(true).
    IncludeState(true).
    Execute()


// For pagination with more than 1,000 occupants
allOccupants := []pubnub.PNHereNowOccupantData{}
limit := 1000
offset := 0


for {
    res, status, err := pn.HereNow().
        Channels([]string{"channel1"}).
        IncludeUUIDs(true).
        IncludeState(true).
        Limit(limit).
        Offset(offset).
        Execute()
    
    if err != nil {
        // Handle error
        break
    }
    
    if channelData, ok := res.Channels["channel1"]; ok {
        allOccupants = append(allOccupants, channelData.Occupants...)
        
        // Check if we've retrieved all occupants
        if len(channelData.Occupants) < limit {
            break
        }
        
        offset += limit
    } else {
        break
    }
}


fmt.Printf("Total occupants retrieved: %d\n", len(allOccupants))

show all 41 lines

New features

UseRawMessage for file messaging

Send file messages without the default "text" JSON wrapper.

res, status, err := pn.SendFile().
    Channel("channel1").
    Message(map[string]interface{}{
        "title": "Important Document",
        "description": "Q4 Report",
    }).
    File(file).
    FileName("q4-report.pdf").
    UseRawMessage(true). // Send message as-is
    Execute()

CustomMessageType for file messages

Specify custom message types for file messages.

res, status, err := pn.PublishFileMessage().
    Channel("channel1").
    Message(pubnub.PNPublishMessage{Text: "File uploaded"}).
    FileID("file-id").
    FileName("document.pdf").
    CustomMessageType("file-upload"). // Custom type
    Execute()

App Context enhancements

Set Status and Type fields on Channel Metadata, UUID Metadata, Channel Member, and Membership.

// Set UUID metadata with Status and Type
res, status, err := pn.SetUUIDMetadata().
    UUID("user-123").
    Name("John Doe").
    Status("active"). // New field
    Type("admin").    // New field
    Execute()


// Set channel metadata with Status and Type
res, status, err := pn.SetChannelMetadata().
    Channel("support").
    Name("Support Channel").
    Status("open").     // New field
    Type("public").     // New field
    Execute()

Conditional metadata updates

Use IfMatchETag to prevent overwriting metadata without fetching the latest version.

// Get current metadata and ETag
getRes, status, err := pn.GetUUIDMetadata().
    UUID("user-123").
    Execute()


if err == nil && getRes.ETag != "" {
    // Update only if ETag matches (prevents conflicts)
    res, status, err := pn.SetUUIDMetadata().
        UUID("user-123").
        Name("John Doe Updated").
        IfMatchETag(getRes.ETag). // Conditional update
        Execute()
    
    if err != nil {
        // Handle conflict (metadata was modified)
        fmt.Println("Metadata was modified by another client")
    }
}

show all 18 lines

Migration steps

To migrate from Go SDK 7.x.x to 8.0.0:

1. Update your dependency:

   go get github.com/pubnub/go/v8

2. Update import statements:

   import (
       pubnub "github.com/pubnub/go/v8"
   )

3. Update push notification types:

   Action	Description
   Replace PNPushTypeMPNS with PNPushTypeFCM or PNPushTypeAPNS2	Microsoft Push Notification Service is no longer supported. Use Firebase Cloud Messaging or Apple Push Notification Service 2 instead.
   Replace PNPushTypeGCM with PNPushTypeFCM	Microsoft Push Notification Service is no longer supported.
   Replace PNPushTypeAPNS with PNPushTypeAPNS2	Apple Push Notification Service is deprecated. Use Apple Push Notification Service 2 instead.

4. Review file message usage:

   Action	Description
   If you use PNPublishMessage.Text with file messages, verify the type works with interface{}	The Text field now accepts interface{} instead of string. This enables sending arbitrary JSON types in file messages.
   Add ShouldStore(true) to SendFile calls if you need message persistence	The ShouldStore parameter in SendFile now defaults to false. Previously, it defaulted to true. If you want file messages stored in Message Persistence, explicitly set ShouldStore(true).

5. Remove Reverse parameter:

   Action	Description
   Remove Reverse() calls from Fetch method	The Reverse parameter is removed from the Fetch method.
   Implement reverse ordering in your application code if needed	If you need messages in reverse order, process the results in your application code.

6. Implement HereNow pagination:

   Action	Description
   If your channels have more than 1,000 occupants, implement pagination logic	The HereNow method now returns a maximum of 1,000 occupants per channel. Use pagination to retrieve more occupants. If your channels have more than 1,000 occupants, your application must use pagination to retrieve the complete list. Use Limit() and Offset() methods for paginated requests

7. Test your application. Pay special attention to push notifications, file messaging, and presence operations.

8. Review deprecation warnings and plan to migrate from deprecated features in future releases.

Additional resources

For API details, see the Go SDK documentation. For questions or issues, contact PubNub support.