Beginning with My Colony v3.0.0 (the tenth anniversary update), players can customize the in-game newsfeed ticker by providing an external URL to an online accessible JSON file containing custom newsfeed templates and information.

In its most simple form, a custom newsfeed in My Colony consists of an accessible online endpoint that returns plain JSON data. This can be either a static file or you can generate the file dynamically on your server in any manner that you choose. The game will fetch/refresh your news data on a regular basis while the player is in-game.

User identification

When fetching your newsfeed, the game will also provide your server with the Ape Apps Account username of the player who is trying to access your newsfeed, if they are signed in and validated, via a URL parameter. You can use this information to customize the news experience on a per-user basis. Examples of unauthenticated and authenticated endpoints:

https://yourserver.com/endpoint.json
https://yourserver.com/endpoint.json?un=username

Note that if your newsfeed endpoint already contains a URL parameter, supposing you require some sort of access key for user validation, the final URL used by the game will be adjusted accordingly.

https://yourserver.com/endpoint.json?key=myawesomekey&un=username

Response template format

When the game calls your newsfeed URL, it expects to receive a valid JSON template with the following structure, which will be explained in more details below.

{
    "feedinfo": {
        "title": "Epic News Service",
        "info": "https://yourserver.com/about.html",
        "author": "apeusername"
    },
    "randomnews": [],
    "newcolony": [],
    "techbreakthrough": []
}

With the exception of the first feedinfo property (which defines general information about your newsfeed), all other base level properties are arrays containing template items:

    "randomnews": [
        {
            "text": "Epic News Service: All of the best My Colony news",
            "color": "#ff0000",
            "icon": "https://yourserver.com/epicnews.png",
            "url": "https://yourserver.com/about.html"
        }
    ]

With the exception of the text property, all news template item properties are optional, and in most cases should actually be either omitted or set to null so that the game will choose its own default colors, icons and callback options.

    "randomnews": [
        {
            "text": "Epic News Service: All of the best My Colony news",
            "color": null
        }
    ]

If set, the color property will set a custom color for your news item in the ticker. It must be a valid hex color code in this format: #ff0000. By default, the game engine automatically assigns certain news colors for specific events, and players will be accustomed to news items showing in the correct color. For this reason, it is generally unnecessary to set a custom color for your news item.

The icon property may contain a full absolute URL to an image file on your server that will show up as a small icon before your news item. Icons are displayed in-game at a DPI adjusted 20x20px size, so in order to look clear on high DPI devices like phones, you should probably provide an icon that is 48x48 or 64x64. Like the color property though, the game will automatically assign certain icons to different news events, so unless you feel a custom icon for your particular news item is needed, it should also be omitted.

The url property, when set, will override the default in-game behavior when a user clicks or taps on your news item and instead open the URL in the user's default web browser. Setting this is probably inappropriate in most circumstances, but there could be edge cases (especially in the randomnews array) when the user may want to find more information about a news item on an external website. Keep in mind though that you do not want to annoy your users, and particularly on mobile devices, being switched to the external web browser application can prove annoying.

The Response Arrays

There are several supported news response arrays in the JSON template that will be called at certain times during gameplay. They will not be called in a particular order, so each time the game calls for an item in one of your response arrays, it will choose one at random. The more items you have in each response array, the better your news feed will look from an end-user perspective.

randomnews

The randomnews array is called occasionally whenever there is nothing specific happening in the colony, yet the news ticker is currently empty and needing a new item. The random news items have no situational context, so they should just be fun and light items to perhaps put a smile on the end user's face!

The randomnews array does support the {colony} and {user} replace variables, for minor customization. For example:

"randomnews": [
    { "text": "{colony} residents agree that {user} is the best mayor in the universe!" }
]

The above template item may produce something like the following in-game: Geubega 4 residents agree that BasedCrusader69 is the best mayor in the universe!

newcolony

The newcolony array is used for ticker items announcing the creation of a new colony on the server. When the user clicks on the news item, they will be taken to the new colony's informational window. These items are helpful for players who wish to send encouraging messages (or resource bundles) to brand new players. This array supports the {colony}, {sector}, {civ}, {maptype}, and {parent} replacement variables.

"newcolony": [
    { "text": "The colony of {colony} has been founded in sector {sector}." },
    { "text": "A new {civ} colony has been established under a charter from {parent}." },
    { "text": "{parent} expands its reach on a new {maptype} in sector {sector}." }
]

techbreakthrough

The techbreakthrough array is called when a new technology is discovered in the players' game or on another online world that the current player has not yet unlocked themselves. It will not show for a new tech that the player already has researched. It accepts the {colony} and {techname} variables. By default, the user will be taken to the tech's encyclopedia entry when clicking on the news item.

"techbreakthrough": [
    { "text": "Scientists on {colony} have unlocked the secrets of {techname}!" }
]

independence

When any online player successfully declares independence from its mother colony, the independence news array is used, supporting the {colony} and {parent} variables. Clicking on the news item defaults for showing the newly independent colonys info screen.

"independence": [
    { "text": "{colony} has just declared independence from {parent}!" }
]  

newfederation

The newfederation array will be called when an online player founds a brand-new Federation. You can use the {federation} and {colony} variables.

"newfederation": [
    { "text": "The {federation} has been founded by {colony}!" }
]