Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                

Create a Tile

Overview

This page walks Technology Partners through creating the tile that represents an offering that will appear on the Integrations or Marketplace page.

Integration tiles

The tile serves as a point of entry where customers can learn about your offering, see setup instructions, and install or purchase your offering to unlock out-of-the-box dashboards and additional assets.

An expanded tile modal of an example offering on the Integrations or Marketplace page

  • For any offerings that do not use the Datadog Agent—including API-based integrations, professional services listings, and software licenses—you only need to create a tile and submit the tile-related files in order to publish your offering. This is called a tile-only-listing. Tile-ony listings apply in situations where Datadog does not host any of the code associated with the API-based integrations, and the other supported offering types do not require any code.

  • For Agent-based integrations, you must create a tile, and additionally, submit all of your integration-related code (as well as your tile-related files) in one pull request. For more information, see Create an Agent-based integration.

Select a tab for instructions on creating a tile on the Integrations or Marketplace page.
    A tile representing an example offering on the Integrations page

    To build a tile on the Integrations page:

    If you have already gone through the steps to create an Agent integration and have built out the scaffolding, you can skip directly to completing the necessary integration asset files.

    1. Create a dd directory:

      mkdir $HOME/dd

      The Datadog Development Toolkit expects you to be working in the $HOME/dd/ directory. This is not mandatory, but working in a different directory requires additional configuration steps.

    2. Fork the integrations-extras repository.

    3. Clone the integrations-extras repository:

      git clone git@github.com:DataDog/integrations-extras.git

    Install and configure the Datadog development toolkit

    The Agent Integration Developer Tool allows you to create scaffolding when you are developing an integration by generating a skeleton of your integration tile’s assets and metadata. For instructions on installing the tool, see Install the Datadog Agent Integration Developer Tool.

    Once you have installed the Agent Integration Developer Tool, configure it for the integrations-extras repository.

    Set integrations-extras as the default working repository:

    ddev config set extras $HOME/dd/integrations-extras
ddev config set repo extras

    If you used a directory other than $HOME/dd to clone the integrations-extras directory, use the following command to set your working repository:

    ddev config set extras <PATH/TO/INTEGRATIONS_EXTRAS>
ddev config set repo extras

    Populate the integration tile scaffolding

    For Datadog API integrations that will be available out-of-the-box on the Integrations page, use the Datadog Development Toolkit to create scaffolding for a tile-only listing.

    1. Make sure you’re inside the integrations-extras directory:

      cd $HOME/dd/integrations-extras

    2. Run the ddev command with the -t tile option:

      ddev create -t tile "<Offering Name>"
    A tile representing an example offering on the Marketplace page

    To build a tile on the Marketplace page:

    If you have already gone through the steps to create an Agent integration and have built out the scaffolding, you can skip directly to completing the necessary integration asset files.

    1. See Build a Marketplace Offering to request access to the Marketplace repository.

    2. Create a dd directory:

      mkdir $HOME/dd

      The Datadog Development Toolkit command expects you to be working in the $HOME/dd/ directory. This is not mandatory, but working in a different directory requires additional configuration steps.

    3. Once you have been granted access to the Marketplace repository, create the dd directory and clone the marketplace repository:

      git clone git@github.com:DataDog/marketplace.git

    4. Create a feature branch to work in:

      git switch -c <YOUR INTEGRATION NAME> origin/master

    Install and configure the Datadog development toolkit

    The Agent Integration Developer Tool allows you to create scaffolding when you are developing an integration by generating a skeleton of your integration tile’s assets and metadata. For instructions on installing the tool, see Install the Datadog Agent Integration Developer Tool.

    Once you have installed the Agent Integration Developer Tool, configure it for the marketplace repository:

    Set marketplace as the default working repository:

    ddev config set marketplace $HOME/dd/marketplace
ddev config set repo marketplace

    If you used a directory other than $HOME/dd to clone the marketplace directory, use the following command to set your working repository:

    ddev config set marketplace <PATH/TO/MARKETPLACE>
ddev config set repo marketplace

    Populate the integration tile scaffolding

    Use the Datadog Development Toolkit to create scaffolding for a tile-only listing.

    To create the tile-only listing’s scaffolding:

    1. Make sure you’re inside the marketplace directory:

      cd $HOME/dd/marketplace

    2. Run the ddev command with the -t tile option:

      ddev create -t tile "<Offering Name>"

    Complete the necessary integration asset files

    Make sure that the following required assets for your integration are complete:

    Asset NameAsset Description
    READMEIncludes an Overview, Setup, Data Collected (optional), and Support section using H2 headings (##) in Markdown.

    For more information, see README.
    MediaAdd any images and a video that you want to use for the integration tile’s media carousel in an images folder. You can add one video to each listing.

    Technology Partners can use .png files instead of .jpg files to reduce image compression.
    Media CarouselDefine the images you want to add to the integration tile’s media carousel in the media object specified in the tile definition on the manifest.json file.

    For more information, see Media Carousel.
    Manifest.jsonSpecify a JSON object that includes elements such as manifest_version,
    display_on_public_website, tile, author, oauth, pricing, assets, and more.

    For more information, see Manifest file.
    Metadata.csvContains a list of out-of-the-box metrics included in the integration defined in the following format ending with a comma: metric_name,metric_type,interval,unit_name,per_unit_name,description,
    orientation,integration,short_name,curated_metric. The metadata.csv file is required for integrations only, not software licenses or professional services.

    For more information, see Metrics metadata file.
    Dashboards and MonitorsProvide the JSON files for out-of-the-box dashboards and monitors included in the integration in the dashboards and monitors folders nested in the assets directory.

    For both dashboards and monitors, a title and description is required. Dashboards and monitors are required for integrations, not software licenses or professional services.

    Technology Partners can create dashboards and monitors in a provisioned sandbox account, and export these assets into JSON files. For more information about dashboards, see Best Practices for Integration Preset Dashboards.
    LogosAdd at least one SVG file which can be used in light and dark modes in a logos folder nested in the assets directory, or add the file(s) directly to the assets directory.

    Technology Partners are responsible for the licensing of submitted logos.
    ChangelogDocument release notes and version information in the Changelog.md file using the following format: 1.0.0 / YYYY-MM-DD. This information is displayed in the Release Notes tab of the integration tile.

    Technology Partners can add releases and version updates in descending order (latest version at the top).
    CODEOWNERSThe CODEOWNERS file belongs in the shared .github directory and defines the individuals or teams responsible for maintaining the content and source code in the Marketplace repository.

    For more information about syntax, see the GitHub code owners documentation.
    End User License Agreement (EULA)Add the eula.pdf file in the assets directory for your Marketplace offering.

    Technology Partners are responsible for adding the EULA.

    README

    Once you have created a README.md file, add the following sections as H2s (##) and fill out the content accordingly:

    Header NameHeader
    OverviewWrite a description under an ## Overview header that describes the value and benefits your offering provides to users, for example, out-of-the-box dashboards, replays of user sessions, logs, alerts, and more.

    This information is displayed in the Overview tab on the tile.
    SetupInclude all the steps required to set up your offering that includes information divided into H3 headings (###).
    Standard topics include:

    - Installing the integration using the in-app integration tile.
    - Configuring the integration with the appropriate roles and permissions in your Datadog organization.
    - Accessing out-of-the-box Datadog features that users who purchased and installed the integration can access (such as metrics, events, monitors, logs, dashboards, and more).
    UninstallationInclude all the steps for uninstalling your offering. This information is displayed in the Configure tab on the tile.
    Data CollectedSpecify the types of data collected by your integration (if applicable), including metrics, events, service checks, and logs. Metrics added to the metadata.csv file automatically appear in this tab.

    If your offering does not provide any of this data, you do not need to add a Data Collected section.
    SupportProvide contact information that includes an email to your Support team, a link to your company’s documentation or blog post, and additional help information in a bulleted list format.

    When adding links to the README.md file, format them using reference-style links. For example, instead of embedding the URL directly in the text, write see the [official Datadog documentation][1] and define the link reference at the bottom of the file like [1]: https://docs.datadoghq.com/.

    For additional grammar and style advice, see also the Datadog documentation contributors guidelines.

    A media carousel of images and a video is displayed on each tile, allowing users to better understand the functionality and value of your offering through visual aids. To add a video to your tile, send a copy or a download link of your video to marketplace@datadoghq.com. The Marketplace team uploads the video and provides a vimeo_link that should be added to the manifest.json file.

    Video

    The video must meet the following requirements:

    Video RequirementsDescription
    TypeMP4 H.264
    SizeThe maximum video size is 1GB.
    DimensionsThe aspect ratio must be 16:9 exactly and the resolution must be 1920x1080 or higher.
    NameThe video file name must be partnerName-appName.mp4.
    Video LengthThe maximum video length is 60 seconds.
    DescriptionThe maximum number of characters allowed is 300.

    Images

    Technology Partners can add up to eight images (seven if you are including a video) in a tile’s media carousel.

    The images must meet the following requirements:

    Image RequirementsDescription
    Type.jpg or .png.
    SizeThe average is around 500KB. The maximum image size is 1MB.
    DimensionsThe aspect ratio must be 16:9 exactly and fit these specifications:

    - Width: 1440px
    - Minimum height: 810px
    - Maximum height: 2560px
    NameUse letters, numbers, underscores, and hyphens. Do not use spaces.
    Color ModeRGB
    Color ProfilesRGB
    DescriptionThe maximum number of characters allowed is 300.

    Follow this template to define the media object in the manifest.json file which includes an image, a video thumbnail, and a video:

    manifest.json

    "media": [
      {
        "media_type": "image",
        "caption": "A Datadog Marketplace Integration OOTB Dashboard",
        "image_url": "images/integration_name_image_name.png"
      },
      {
        "media_type": "video",
        "caption": "A Datadog Marketplace Integration Overview Video",
        "image_url": "images/integration_name_video_thumbnail.png",
        "vimeo_id": 123456789
      },
    ],

    For more information, see Integrations Assets Reference.

    Open a pull request

    Before you open a pull request, run the following command to catch any problems with your integration:

    ddev validate all <INTEGRATION_NAME>

    Complete the following steps:

    1. Commit all changes to your feature branch.
    2. Push your changes to the remote repository.
    3. Open a pull request that contains your integration tile’s asset files (including images) in the marketplace or integrations-extras repository.

    After you’ve created your pull request, automatic checks run to verify that your pull request is in good shape and contains all the required content to be updated.

    Review process

    Once your pull request passes all checks, reviewers from the Datadog/agent-integrations, Datadog/ecosystems-review, and Datadog/documentation teams provide suggestions and feedback on best practices.

    Once you have addressed the feedback and re-requested reviews, these reviewers approve your pull request. Contact the Marketplace team if you would like to preview the tile in your sandbox account. This allows you to validate and preview your tile before your tile goes live to all customers.

    Troubleshoot errors

    Out-of-the-box integrations in the integrations-extras repository can run into validation errors when the forked repository is out of date with the origin.

    To resolve validation errors, update the forked repository on the GitHub web app:

    1. In GitHub, navigate to your forked integrations-extras repository.
    2. Click Sync fork and click Update branch.

    To rebase and push changes:

    1. Update your local master branch:
      git checkout master
git pull origin master
    2. Merge master into your feature branch:
      git checkout <your working branch>
git merge master
    3. If there are any merge conflicts, resolve them. Then, run git push origin <your working branch>.

    Go-to-Market (GTM) opportunities

    Datadog offers GTM support for Marketplace listings only. To learn more about the Datadog Marketplace, see Create a Marketplace Offering.

    Further reading

    Additional helpful documentation, links, and articles:

    Expand your monitoring reach with the Datadog MarketplaceBLOG more more Create an offering on the Datadog MarketplaceDOCUMENTATION more more