Analytics Services - Design Considerations

  • Article

The Design Considerations Guide includes recommendations and guidance when you are integrating with Sales Navigator Analytics Services.

Building a Contract Chooser

All export jobs for analytics data are created in the context of a contract, so it is necessary to build a contract chooser to enable the user to select the contracts for which they want to export data. For more information on how to get the list of contracts for a user, see /salesContracts.

Creating Successful Export Jobs

  • It's recommended to provide users a list of pre-defined date ranges, such as 1 week, 1 month, and 3 months to help users easily select date rages. The maximum date range we support for an export job is 90 days.
  • Create jobs using day boundaries only, rather than giving datetime pickers to users. This makes incremental refresh much easier.
  • Make sure the date range is valid when you are exporting the analytics data. The criteria for a valid range can be found in exportActivityData
  • Since export data is refreshed every 24 hours, do not build your integration to repeatedly creates jobs looking for data within the past 24 hours.
  • When polling periodically for an export job's status, it is recommended to set an appropriate polling interval to avoid unnecessary calls, and to stop polling once the export job has completed.

Error Handling

The export job may not be created or completed successfully due to various reasons. Instead of ignoring the 4xx or 5xx status code, make sure the corresponding errors are handled in your integration and users are presented with the appropriate information to decide the correct course of action. Here are a list of potential error codes that your application should handle.

Response Code Description
400 Bad request, missing parameter
401 Unauthorized (typically a result of token expiration)
403 User does not have enough access to complete the request. Some example cases of insufficient access are:
  • "User does not have reporting permission on Sales Navigator contract"
  • "User does not have any assigned permission on Sales Navigator contract"
409 Maximum number of requests enqueued for this export type. See Throttling and Limits for more info
500 Unhandled service error
503 Service unavailable due to high demand

Refer to API Guide - Error Handling for more details.

Throttling and Limits

Only one query can be in progress at a time per user, per export type, per contract. If an additional request is made for an export type, there will be a 409 response with a message indicating that a job is already enqueued or processing for this export type. New requests for this user, export type, and contract will not be successful until the previous request for that export is completed. Read Error Handling - 429 Rate Limit to learn more about throttling and limits.

Logout from authentication

Your users might want to logout from the authentication or switch to a different LinkedIn account within your product. In this case, your product should provide "logout" or "unlink" option for users after they have successfully authorized the authentication. The tokens stored on both client or server should be removed upon logout.

Important

In order to allow users to successfully switch LinkedIn accounts authenticated to your integration, you can direct users to switch their account on www.linkedin.com before authenticating a different LinkedIn account to your integration.