Viz Social Deployment Guide

Version 1.1 | Published January 26, 2022 ©

Submission of Individual Posts

Submission via JSON Files

Viz Social is able to accept Posts generated by external sources. Out-of-the-box, this is supported via files formatted in Viz Social’s native POST JSON format.

Syntax by Example

Each series of external Posts must be formatted as an items array of Posts. Please find an example of such an array below:

{
  "items": [
    {
      "id": 1,
      "sticky": true,
      "author": "Malorie Espinoza",
      "nickname": "malorieespinoza",
      "profile_id": 384,
      "profile_image_url": "https://example.never.no/test/img/profile-01.jpg",
      "title": "Message #1",
      "message": "My favourite Pokémon is #291 Ninjask​ #pokemon #pokemongo ​",
      "timestamp": "1534862969020",
      "permalink": "https://example.never.no/messages/index.php?ref=eyJpZCI6MSwidWlkIjozODQsIm1pZCI6MjkwLCJpaWQiOjIsInVybCI6NiwidHMiOjE1MzQ4NjI5NjksIm1zIjoiMTUzNDg2Mjk2OTAyMCJ9",
      "images": [
        { "url": "https://example.never.no/test/img/pokemon/291.png" },
        { "url": "https://example.never.no/test/img/img-01.jpg" }
      ],
      "videos": [
        { "url": "https://example.never.no/test/video/small.mp4" }
      ],
      "links": [
        { "url": "http://www.pokemon.com/no/pokedex/ninjask​" }
      ]
    },
 
    {
      "id": "2",
      "sticky": false,
      "author": "Iva Carney",
      "nickname": "ivacarney",
      "profile_id": 353,
      "profile_image_url": "https://example.never.no/test/img/profile-02.jpg",
      "title": "Message #2",
      "message": "My favourite Pokémon is #701 Hawlucha​ #pokemon #pokemongo​",
      "timestamp": "1534862969021",
      "permalink": "https://example.never.no/messages/index.php?ref=eyJpZCI6MiwidWlkIjozNTMsIm1pZCI6NzAwLCJpaWQiOjksInVybCI6MSwidHMiOjE1MzQ4NjI5NjksIm1zIjoiMTUzNDg2Mjk2OTAyMSJ9",
      "images": [
        { "url": "https://example.never.no/test/img/pokemon/701.png" },
       { "url": "https://example.never.no/test/img/img-02.jpg" }
      ],
      "videos": [],
      "links": [
        { "url": "http://www.pokemon.com/no/pokedex/hawlucha​" }
      ]
    },
 
    {
      "id": "3",
      "sticky": false,
      "author": "Philomena Stephens",
      "nickname": "philomenastephens",
      "profile_id": 685,
      "profile_image_url": "https://example.never.no/test/img/profile-03.jpg",
      "title": "Message #3",
      "message": "My favourite Pokémon is #718 Zygarde​ #pokemon #pokemongo​",
      "timestamp": "1534862969022",
      "permalink": "https://example.never.no/messages/index.php?ref=eyJpZCI6MywidWlkIjo2ODUsIm1pZCI6NzE3LCJpaWQiOjcsInVybCI6NywidHMiOjE1MzQ4NjI5NjksIm1zIjoiMTUzNDg2Mjk2OTAyMiJ9",
      "images": [
        { "url": "https://example.never.no/test/img/pokemon/718.png" },
        { "url": "https://example.never.no/test/img/img-03.jpg" }
      ],
      "videos": [],
      "links": [
        { "url": "http://www.pokemon.com/no/pokedex/zygarde​" }
      ]
    },
 
    {
      "id": "4",
      "sticky": false,
      "author": "Beckie Cannon",
      "nickname": "beckiecannon",
      "profile_id": 325,
      "profile_image_url": "https://example.never.no/test/img/profile-04.jpg",
      "title": "Message #4",
      "message": "My favourite Pokémon is #104 Cubone​ #pokemon #pokemongo​",
      "timestamp": "1534862969024",
      "permalink": "https://example.never.no/messages/index.php?ref=eyJpZCI6NCwidWlkIjozMjUsIm1pZCI6MTAzLCJpaWQiOjYsInVybCI6NywidHMiOjE1MzQ4NjI5NjksIm1zIjoiMTUzNDg2Mjk2OTAyNCJ9",
      "images": [
        { "url": "https://example.never.no/test/img/pokemon/104.png" },
        { "url": "https://example.never.no/test/img/img-04.jpg" }
      ],
      "videos": [],
      "links": [
        { "url": "http://www.pokemon.com/no/pokedex/cubone​" }
      ]
    },
 
    {
      "id": "5",
      "sticky": false,
      "author": "Janie Goodman",
      "nickname": "janiegoodman",
      "profile_id": 651,
      "profile_image_url": "https://example.never.no/test/img/profile-05.jpg",
      "title": "Message #5",
      "message": "My favourite Pokémon is #709 Trevenant​ #pokemon #pokemongo​",
      "timestamp": "1534862969030",
      "permalink": "https://example.never.no/messages/index.php?ref=eyJpZCI6MTAsInVpZCI6NjUxLCJtaWQiOjcwOCwiaWlkIjoxLCJ1cmwiOjMsInRzIjoxNTM0ODYyOTY5LCJtcyI6IjE1MzQ4NjI5NjkwMzAifQ%3D%3D",
      "images": [
        { "url": "https://example.never.no/test/img/pokemon/709.png" },
        { "url": "https://example.never.no/test/img/img-5.jpg" }
      ],
      "videos": [],
      "links": [
        { "url": "http://www.pokemon.com/no/pokedex/trevenant​" }
      ]
    }
 
  ],
  "paging": {
    "count": 5,
    "min_id": 1,
    "max_id": 5,
    "next_min_id": 6,
    "prev_min_id": null,
    "next_url": "https://example.never.no/messages/index.php?count=5&min_id=6",
    "prev_url": null
  }
}

Semantics

Post Field Definitions

The following table contains the definitions of the POST fields and parameters.

Field

Description

Required

id

Unique message ID.

Yes

sticky

If set to true, the message is sticky (always shown on top of the posts).

No

author

Full name of the author.

No

nickname

Nickname or alias of the author.

No

profile_id

Profile ID.

No

profile_image_url

URL to profile image / avatar.

No

title

Message title, if applicable.

No

message

Message text.

No

timestamp

Timestamp created. Unix timestamp in milliseconds (other formats can be supported on request).

No

permalink

External link to the posted message.

No

images.url

Array with URLs of attached images.

No

videos.url

Array with URLs of attached videos.

No

links.url

Array with associated links.

No

Paging

Paging is supported via the dedicated data structure at the end of the example in Syntax by Example. The request from Viz Social uses the request parameters specified in Request Parameters.

Request Parameters

Parameter

Description

Required

count

Maximum number of posts per return page.

Yes

min_id

The documents returned should not have an ID lower than min_id.

No

Response Parameters

The response is expected to transmit the response parameters specified by the Request Parameters.

Field

Description

Required

count

Number of posts returned in this page. Might be less than the number that was asked for.

Yes

min_id

Minimal ID returned in this page.

No

max_id

Maximum ID returned in this page.

No

next_min_id

Minimum ID to be used by Viz Social to retrieve the next page.

Yes

next_url

Suggested URL to be used by Viz Social to retrieve the next page.

Yes

Example: The response to the query: GET https://code.never.no/messages/index.php?count=10&min_id=11 might be:

{
  "items": [
    {
      "id": 11,
    },
    ..
    {
      "id": 20
    }
  ],
  "paging": {
    "count": 10,
    "min_id": 11,
    "max_id": 20,
    "next_min_id": 21,
    "next_url": "https://code.never.no/messages/index.php?count=10&min_id=21"
  }
}

Business Logic

Please take note of the following business logic when integrating an external source of social Posts:

  • The examples in Syntax by Example show the widest supported set of fields and parameters. Most fields are optional, see Post Field Definitions.

  • Post must have a monotonously increasing id.

  • The first request from Viz Social usually leaves out min_id. It is up to the server to decide where to set the initial cursor. A suggested option is to respond with the most recent count posts (or less of there aren’t that many).

  • It could be that no new records are available when a request comes in. In that case, the server is expected to respond with a count of 0, without the min_id and max_id.

Dynamics

Files with social posts from external sources must be delivered at a well-defined path. File access, transport and naming conventions are not prescribed. After having been agreed to, they form input to Never.no’s integration services.

Submission in Other Formats

Social posts in alternative JSON formats or even via RSS/Atom feeds or plain XML, can often be supported via customized pre-processing on Viz Social.

Important: Customization options should be discussed with Never.no. Please contact the Never.no support team to discuss options and to come to an optimal solution.